@sangyaahub/pi-marg 1.0.0

package/scripts/setup-codegraph.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mode="dry-run"
+repo_path="${PWD}"
+
+if [[ "${1:-}" == "--apply" ]]; then
+  mode="apply"
+  shift
+fi
+
+if [[ $# -gt 1 ]]; then
+  echo "Usage: $0 [--apply] [repository-path]" >&2
+  exit 2
+fi
+
+if [[ $# -eq 1 ]]; then
+  repo_path="$1"
+fi
+
+if [[ ! -d "${repo_path}" ]]; then
+  echo "Repository path is not a directory: ${repo_path}" >&2
+  exit 1
+fi
+
+repo_root="$(git -C "${repo_path}" rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "${repo_root}" ]]; then
+  echo "Not a Git repository: ${repo_path}" >&2
+  exit 1
+fi
+
+echo "Repository: ${repo_root}"
+
+if [[ "${mode}" == "dry-run" ]]; then
+  if command -v codegraph >/dev/null 2>&1; then
+    echo "[ok] CodeGraph CLI is installed"
+  else
+    echo "[would install] npm install -g @colbymchenry/codegraph@latest"
+  fi
+  if [[ -d "${repo_root}/.codegraph" ]]; then
+    echo "[would verify] codegraph status \"${repo_root}\""
+  else
+    echo "[would initialize] codegraph init \"${repo_root}\""
+  fi
+  echo "Run $0 --apply \"${repo_root}\" to make these changes."
+  exit 0
+fi
+
+if ! command -v codegraph >/dev/null 2>&1; then
+  if ! command -v npm >/dev/null 2>&1; then
+    echo "npm is required to install CodeGraph." >&2
+    exit 1
+  fi
+  npm install -g @colbymchenry/codegraph@latest
+fi
+
+if [[ ! -d "${repo_root}/.codegraph" ]]; then
+  codegraph init "${repo_root}"
+fi
+
+codegraph status "${repo_root}"
+echo "CodeGraph is ready. Restart the active Pi or OMP session if this is the first installation so its integration can be detected."

package/scripts/validate.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+package_root="$(cd "${script_dir}/.." && pwd)"
+build_dir="$(mktemp -d)"
+trap 'rm -rf "${build_dir}"' EXIT
+
+cd "${package_root}"
+
+for script in scripts/*.sh; do
+  bash -n "${script}"
+done
+
+bun -e '
+  import { existsSync } from "node:fs";
+  const packageJson = await Bun.file("package.json").json();
+  const marketplace = await Bun.file(".omp-plugin/marketplace.json").json();
+  if (packageJson.name !== "@sangyaahub/pi-marg") throw new Error("Unexpected package name");
+  if (packageJson.version !== "1.0.0") throw new Error("package.json must be v1.0.0");
+  if (packageJson.license !== "MIT") throw new Error("package.json must declare MIT");
+  if (packageJson.author !== "Sangyaa") throw new Error("Unexpected package author");
+  if (!packageJson.keywords?.includes("pi-package")) throw new Error("Pi catalog keyword is missing");
+  if (marketplace.name !== "pi-marg-marketplace") throw new Error("Unexpected marketplace name");
+  if (marketplace.metadata?.version !== packageJson.version) throw new Error("Marketplace version mismatch");
+  if (marketplace.plugins?.[0]?.version !== packageJson.version) throw new Error("Plugin version mismatch");
+  if (marketplace.plugins?.[0]?.name !== packageJson.name.split("/").at(-1)) throw new Error("Plugin/package name mismatch");
+  if (marketplace.plugins?.[0]?.source !== "./") throw new Error("OMP local source must begin with ./");
+  for (const relativePath of [
+    ...(packageJson.pi?.extensions ?? []),
+    ...(packageJson.pi?.skills ?? []),
+    ...(packageJson.pi?.prompts ?? []),
+    ...(packageJson.omp?.extensions ?? []),
+  ]) {
+    if (!existsSync(relativePath)) {
+      throw new Error(`Manifest path does not exist: ${relativePath}`);
+    }
+  }
+  const license = await Bun.file("LICENSE").text();
+  if (!license.includes("MIT License") || !license.includes("Copyright (c) 2026 Sangyaa and PiMarg contributors")) {
+    throw new Error("LICENSE is not the expected MIT license");
+  }
+  const demo = await Bun.file("demo/pi-marg-v1.0.html").text();
+  if (!demo.includes("PiMarg") || !demo.includes("v1.0")) {
+    throw new Error("Demo branding/version mismatch");
+  }
+  if (!existsSync("assets/pi-marg-banner.png") || !existsSync("assets/brand/sangyaa-mark.png")) {
+    throw new Error("PiMarg brand assets are missing");
+  }
+  const readme = await Bun.file("README.md").text();
+  if (!readme.includes("# PiMarg") || !readme.includes("sangyaahub/pi-marg")) {
+    throw new Error("README branding or install target mismatch");
+  }
+  for await (const path of new Bun.Glob("skills/*/SKILL.md").scan(".")) {
+    const text = await Bun.file(path).text();
+    if (!text.startsWith("---\n") || !/\nname:\s*\S+/.test(text) || !/\ndescription:\s*.+/.test(text)) {
+      throw new Error(`Invalid skill frontmatter: ${path}`);
+    }
+  }
+  for await (const path of new Bun.Glob("**/*").scan({ cwd: ".", onlyFiles: true })) {
+    if (path === "scripts/validate.sh") continue;
+    if (/\.(?:png|jpe?g|gif|webp)$/i.test(path)) continue;
+    const text = await Bun.file(path).text();
+    if (text.includes("*** Begin Patch") || text.includes("*** Add File:")) {
+      throw new Error(`Patch marker leaked into artifact: ${path}`);
+    }
+  }
+  console.log("[ok] manifests, paths, MIT license, demo, and skill frontmatter");
+'
+
+bun build core/*.ts adapters/pi/extensions/*.ts adapters/omp/extensions/*.ts \
+  --outdir "${build_dir}" --target bun --external typebox >/dev/null
+
+echo "[ok] TypeScript core and adapters compile"
+echo "[ok] shell scripts parse"

package/skills/auto-mode-addons/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: auto-mode-addons
+description: Route optional PiMarg support for code simplification, approved persistent memory, language-specific guidance, and cost control on Pi or OMP. Use after intake when Ponytail, Hindsight/local memory, Go/Python/TypeScript guidance, or lower-cost routing is requested or configured.
+---
+
+# PiMarg Add-ons
+
+Load only the reference needed for the active task:
+
+- For minimal implementation or an over-engineering review, read [ponytail.md](references/ponytail.md).
+- For runtime-specific Hindsight memory or backup policy, read [hindsight.md](references/hindsight.md).
+- For Go, Python, or TypeScript guidance, read [language-skills.md](references/language-skills.md).
+- For model and token budget decisions, read [cost-control.md](references/cost-control.md).
+
+An add-on supplies constraints, memory, or evidence. The primary Compound Engineering, Superpowers, or GSD spine still owns task state and the authoritative plan. Verify the upstream capability is installed and discovered before saying it ran.

package/skills/auto-mode-addons/references/cost-control.md

@@ -0,0 +1,24 @@
+# Cost control
+
+Spend frontier tokens where they change the decision, not on mechanical work.
+
+```text
+A  discovery      frontier, bounded context, one decision artifact
+C  plan review    different frontier model, plan + risks only
+B  implementation mid-layer/included model, approved plan + CodeGraph context
+D  code review    different mid-layer model, diff + tests + acceptance criteria
+```
+
+Rules:
+
+- Use `auto_model_route catalog` at selection time; never maintain a static version list.
+- Prefer Cursor Composer or a zero-metered/included Cursor entry for routine B execution when quality is sufficient. “Zero-metered” does not mean unlimited or free; check plan quotas.
+- Use Devin for bounded, parallelizable execution with explicit acceptance criteria and an ACU/session limit. Creating a session is a `post-web` action.
+- Keep C focused on the plan, decisions, and highest-cost risks. Keep D focused on the diff, affected contracts, and test evidence.
+- Use CodeGraph to retrieve surgical source context instead of sending whole directories.
+- Keep Hindsight recall at `low` or 512 tokens by default. Increase only when missing memory measurably causes rework.
+- Use checkpoint/rewind only around a genuinely disposable research/debug branch; its report should preserve the evidence while removing noisy transcript context.
+- Keep the advisor off for routine low-risk work. When enabled, use a cheaper distinct reviewer that can catch the targeted failure mode, then verify `/advisor status` usage.
+- Reuse provider prompt caches when the active Pi/OMP route supports them; keep stable instructions at the front and variable task data later.
+- Escalate B or D to a frontier model only after a mid-layer attempt fails a concrete check or the change is high risk.
+- Record per-stage provider, model, effort, observed outcome, and—when available—usage. Tune from real task cost, not token price alone.

package/skills/auto-mode-addons/references/hindsight.md

@@ -0,0 +1,54 @@
+# Hindsight memory and backup
+
+Use Hindsight only through an integration the active runtime actually exposes. `auto_runtime_status` must detect the relevant memory tools before the workflow claims recall or retention occurred.
+
+## Configure securely
+
+### OMP
+
+OMP provides a native Hindsight backend. Use `/settings` or OMP configuration:
+
+```yaml
+memory:
+  backend: hindsight
+hindsight:
+  apiUrl: http://localhost:8888
+  scoping: per-project
+  autoRecall: true
+  autoRetain: false
+  recallBudget: low
+  recallMaxTokens: 512
+```
+
+The default endpoint is local. When authentication is required, set `HINDSIGHT_API_TOKEN` in the user's secure environment; never put the token in this plugin, a prompt, the ledger, or a repository.
+
+Use `per-project` for hard client/employer isolation. `per-project-tagged` may mix untagged global recall with project-tagged memory and therefore requires an explicit policy decision for sensitive work.
+
+Run `/memory diagnose` after configuration. If `auto_runtime_status` does not show the native memory context plus the expected recall/retain/reflect tools, treat Hindsight as unavailable.
+
+### Pi
+
+Pi does not receive OMP's native Hindsight backend from this package. Install or create a trusted Pi memory extension that exposes explicit `recall` and `retain` tools, configure it according to Hindsight's current documentation, and verify it with `auto_runtime_status`. Until those tools appear, keep memory off and use the local Markdown lesson only.
+
+## Session policy
+
+- Job/client: default memory to off. Enable recall or retention only after confidentiality and retention policy allow the selected service and bank.
+- Personal: recommend recall-only first; enable retention after the first successful diagnostic.
+- At session start, recall only facts relevant to the confirmed context and repository.
+- Treat recalled memory as heuristic and verify it against the current repository.
+- At close, write `lessons.md` first, then retain only verified decisions, conventions, and the reusable lesson summary.
+- Never retain secrets, credentials, raw client data, personal data, large source dumps, noisy transcripts, or unvalidated hypotheses.
+
+Do not assume a `memory_edit` tool exists. Use Hindsight's supported UI/API for server-side deletion or correction, with the applicable approval gate.
+
+## Backup policy
+
+For self-hosted PostgreSQL or pg0, create a consistent full backup with:
+
+```bash
+hindsight-admin backup /secure-backups/hindsight-YYYY-MM-DD.zip
+```
+
+Keep at least one encrypted copy on a different device or storage provider. Prefer a versioned Backblaze B2 or S3-compatible bucket for low-cost automation, or Google Drive for a simpler manual route. Uploading the copy requires `post-web` approval. Verify the archive and periodically test restoration into a fresh disposable schema or instance.
+
+`hindsight-admin restore` deletes the target schema before import. Show the exact target and obtain `delete-remove` approval first. Use bank export/import for portability when supported, prefer a fresh target bank, and verify counts after import.

package/skills/auto-mode-addons/references/language-skills.md

@@ -0,0 +1,54 @@
+# Language skill routing
+
+Load language guidance only after the repository language is observed. On existing repositories, detect this from CodeGraph's file/language summary, not a grep/glob crawl.
+
+Use the smallest relevant subset. Do not install an entire large collection merely because one language is present.
+
+## Go
+
+Repository: `https://github.com/samber/cc-skills-golang`
+
+Suggested base:
+
+```bash
+npx skills add samber/cc-skills-golang --skill golang-code-style
+npx skills add samber/cc-skills-golang --skill golang-error-handling
+npx skills add samber/cc-skills-golang --skill golang-testing
+```
+
+Add concurrency, security, performance, or gopls skills only when that concern exists.
+
+## Python
+
+Repository: `https://github.com/wshobson/agents`
+
+Suggested base:
+
+```bash
+npx skills add wshobson/agents --skill python-code-style
+npx skills add wshobson/agents --skill python-type-safety
+npx skills add wshobson/agents --skill python-testing-patterns
+```
+
+Add async, packaging, performance, or error-handling guidance only when relevant.
+
+## TypeScript
+
+Repositories: `https://github.com/wshobson/agents` and `https://github.com/cursor/plugins`
+
+Suggested base:
+
+```bash
+npx skills add cursor/plugins --skill typescript-best-practices
+npx skills add wshobson/agents --skill javascript-testing-patterns
+```
+
+Load `typescript-advanced-types` only when the change genuinely needs non-trivial type-level design; it is not a default style guide.
+
+## Stage rule
+
+- Stage A: load architecture/style guidance only when it informs a material design decision.
+- Stage B: load the base style and testing skills for languages in the actual edit scope.
+- Stage C/D: load the relevant language review/testing guidance, not every build skill again.
+
+These are community skills. Review the selected `SKILL.md`, repository activity, license, requested tools, and current skills.sh security signals before global installation. After installation, verify the exact skill appears in the active Pi or OMP inventory; otherwise treat it as unavailable.

package/skills/auto-mode-addons/references/ponytail.md

@@ -0,0 +1,41 @@
+# Ponytail integration
+
+Ponytail is a supporting minimalism filter, not the task's planner.
+
+## Recommended placement
+
+```text
+Stage A: understand the real need and code flow
+    ↓
+Ponytail lite: challenge speculative scope or a new dependency
+    ↓
+Stage B: Ponytail full while implementing the approved slice
+    ↓
+tests pass
+    ↓
+Stage D: ponytail-review on the diff, then normal correctness review
+```
+
+Use CodeGraph first on an existing repository. Ponytail's ladder runs only after the relevant flow is understood:
+
+1. Skip a requirement that is genuinely unnecessary.
+2. Reuse an existing repository pattern.
+3. Prefer the standard library.
+4. Prefer a native platform feature.
+5. Prefer an already-installed dependency.
+6. Write the minimum correct code.
+
+Keep `full` as the normal build setting. Use `lite` during architecture when the user should choose between the requested design and a smaller option. Avoid `ultra` for authentication, authorization, money, personal/client data, destructive behavior, concurrency, or migrations.
+
+Never remove trust-boundary validation, data-loss handling, security controls, accessibility, acceptance behavior, or the smallest useful regression test. `ponytail-review` finds complexity only; it does not replace correctness or security review.
+
+## Installation
+
+Ponytail publishes a Claude-compatible marketplace and a Pi package. For OMP's Claude-marketplace compatibility path:
+
+```bash
+omp plugin marketplace add DietrichGebert/ponytail
+omp plugin install --scope user ponytail@ponytail
+```
+
+Restart OMP and verify `ponytail` plus `ponytail-review` appear. If the installed OMP release does not discover the compatibility package, use Ponytail's documented Pi install for the Pi harness or copy its instruction-only `AGENTS.md` policy; do not claim the OMP skill loaded until discovery succeeds.

package/skills/auto-mode-router/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: auto-mode-router
+description: Classify a new work request, select one development-method skill spine, route live stage models and tools on Pi or OMP, and maintain the PiMarg session ledger. Use at the start of each new substantive task; do not restart it for ordinary follow-ups.
+---
+
+# PiMarg Router
+
+Turn a user request into one controlled workflow.
+
+1. Read [intake-and-state.md](references/intake-and-state.md) and complete the intake stages in order.
+2. After the user selects mode 1–4, read [routing-matrix.md](references/routing-matrix.md) and select exactly one primary skill spine.
+3. Read [session-ledger.md](references/session-ledger.md), create the neutral Markdown ledger, and identify the selected spine's authoritative planning artifact.
+4. Read [models-and-tools.md](references/models-and-tools.md). Call `auto_model_route` with `action: catalog` and the confirmed work type, present the live choices, and save each required A/B/C/D selection. The runtime rejects A=C and B=D.
+5. Call `auto_runtime_status`. If it reports `OMP`, read [native-omp-runtime.md](references/native-omp-runtime.md); if it reports `Pi`, read [native-pi-runtime.md](references/native-pi-runtime.md). Record which advisor, task, review, checkpoint/rewind, code-intelligence, debugger, browser/desktop, security, and memory routes are actually available.
+6. For work types 2–6, load `codegraph-first` and pass its bootstrap gate before making repository-wide architecture or impact claims. CodeGraph owns those claims when available. LSP, AST, compiler, and repository-native tools may handle precise operations; missing CodeGraph must be recorded rather than concealed behind broad grep output.
+7. Load `auto-mode-addons` only for requested or configured Ponytail, Hindsight, language-specific, or cost-control support. An add-on never becomes a second workflow spine.
+8. Before each routed stage, call `auto_model_route` with `action: activate` for that stage. Verify installed skills and tools before invoking them; never imitate a missing capability while claiming it ran.
+9. Run A → C → B → conditional verification → D, adjusted by work type. Use an advisor only as an optional watcher, task fan-out only when a compatible tool exists and work is independent, and checkpoint/rewind only when the runtime provides their documented semantics. Keep decisions and evidence current.
+10. After D and any required security review pass, offer the runtime's local commit path (`omp commit` on OMP or a repository-native local commit on Pi); never include a push. Ask only when a missing choice materially changes the result or permission.
+11. Before final completion, load `session-lessons`. Run it once and only once for this session, then retain/learn the verified summary only when memory is available and approved.
+
+The approval extension may block protected tool calls. Treat a block as a required user checkpoint, not as a reason to bypass the guard through another tool.

package/skills/auto-mode-router/references/intake-and-state.md

@@ -0,0 +1,124 @@
+# Intake and session state
+
+## State machine
+
+```text
+NEW
+ │
+ ▼
+CONTEXT ─► TYPE ─► SKILL MODE ─► MODELS ─► RUNTIME ─► ADD-ONS ─► READY
+            ▲                                                   │
+            └────────────────── clarify only ◄──── ACTIVE ◄─────┘
+                                                        │
+                                                        ▼
+                                                      CLOSED
+```
+
+Ask one intake stage at a time. A clear user prompt can support a proposed classification, but it does not remove the required confirmation.
+
+## Stage 1 — work context
+
+Ask first:
+
+> Is this for your job/client, or is it personal work?
+
+Record exactly one:
+
+- `job-client`: Do not add Sangyaa branding, name, logo, metadata, footer, or promotional language. Use the employer/client/project brand already in scope.
+- `personal`: Existing project branding wins. Sangyaa branding is opt-in, never automatic.
+
+Do not start code, research, or planning before this answer unless the user is asking only how Auto Mode itself works.
+
+## Stage 2 — work type
+
+Infer the most likely type, state it plainly, and ask the user to confirm. If ambiguous, show the relevant choices only.
+
+1. New idea or development from scratch: brainstorming and analysis.
+2. New feature for an existing repository.
+3. Improve an existing feature in an existing repository.
+4. Proactive bug discovery or bug fix in an existing repository.
+5. Security review or security fixes.
+6. Thoughts, explanation, or another question about an existing repository or feature.
+7. Business, sales, or other non-technical analysis.
+
+If one request contains multiple types, pick the type that owns the immediate outcome and record later types as follow-on phases. Do not open multiple workflow spines.
+
+## Stage 3 — skill mode
+
+Ask:
+
+> Which method should own this task: 1) Compound Engineering, 2) Superpowers, 3) GSD Core, or 4) choose the best one for me?
+
+- Mode 1: use the Compound Engineering mapping for the confirmed work type.
+- Mode 2: use the Superpowers mapping.
+- Mode 3: first verify that GSD skills and their required tools are available in the active runtime. If not, explain the incompatibility and offer a supported alternative.
+- Mode 4: choose one primary spine using the routing criteria. Explain the choice in one short sentence and ask for confirmation only if the trade-off is material.
+
+## Stage 4 — live model choices
+
+Call `auto_model_route` with `action: catalog` and the confirmed work type. Present only selectors returned by the tool; do not type a remembered model ID.
+
+The four roles are:
+
+- A — thinking/discovery using a current Claude Fable/Opus, OpenAI Astra/Sol, or Grok 4.6-or-newer frontier model.
+- B — coding/execution using a current Claude or OpenAI mid-layer model, Cursor Composer, a zero-metered Cursor/Devin route, native Devin SWE, or an external Devin MCP session.
+- C — plan second-eye using the A frontier pool, but not the same underlying model selected for A.
+- D — implementation/code second-eye using the B execution pool, but not the same underlying model selected for B.
+
+Ask only for stages required by the current work type. Work types 2–3 normally use A → C → B → D. Type 4 uses A → B → D and adds C only for a non-trivial plan. Types 1, 6, and 7 use A → C. Type 5 uses A → C for review and adds B → D when fixes are authorized.
+
+Use `action: select` for each answer. The active adapter saves exact selectors in session state and immediately activates the selected runtime model. Native `devin/swe-*` selectors behave like other models. An external Devin session requires `post-web` approval before creation.
+
+## Stage 5 — native runtime and supporting capabilities
+
+Call `auto_runtime_status` before making a recommendation. Distinguish `available`, `enabled`, and `used`; a tool installed but gated off did not run.
+
+For an existing repository, CodeGraph is mandatory. Verify the CLI and graph before any source reference.
+
+Offer a compact recommended set and let the user change it:
+
+- Orchestration: serial, direct `task` batch, or explicit `workflowz`; recommend serial for small/overlapping changes and task fan-out only for independent units.
+- Advisor: off or supplemental watcher; recommend it for moderate/high-risk work when a distinct model is configured and its extra usage is acceptable. It never replaces C/D.
+- Context pruning: use checkpoint/rewind only for a long disposable research or debugging branch, and only when both tools are available.
+- Ponytail: off, lite, or full; recommend full for normal B implementation and `ponytail-review` before D correctness review.
+- Memory: off, detected local memory, Hindsight recall-only, or Hindsight recall-and-retain; default job/client work to off until retention is permitted.
+- Language skills: automatically detect Go, Python, and TypeScript in the actual scope, then load only installed relevant skills.
+- Cost posture: economy, balanced, or quality; recommend balanced unless risk or user intent says otherwise.
+- Verification: infer repository checks, DAP debugging, browser/desktop QA, and security review from the work type and affected surface. Let the user remove only gates whose consequence is understood.
+- Collaboration: off by default. `/collab` and `/share` require `post-web` approval.
+
+## Session reuse
+
+After intake, emit a compact conversational state block and save the same facts in the ledger:
+
+```text
+[AUTO-MODE]
+context: job-client | personal
+type: 1..7
+mode: 1..4
+spine: compound-engineering | superpowers | gsd | none
+models: A=<selector> B=<selector|n/a> C=<selector> D=<selector|n/a>
+runtime: advisor=<off|available|on|unavailable> orchestration=<serial|task|workflowz> checkpoint=<off|available|used>
+addons: ponytail=<off|lite|full> memory=<off|local|hindsight-recall|hindsight-retain> language=<names|none> cost=<economy|balanced|quality>
+verification: tests=<planned|n/a> dap=<planned|n/a> ui=<browser|desktop|n/a> security=<planned|n/a>
+collaboration: off | view-approved | write-approved
+commit: not-ready | offered | created | skipped
+codegraph: n/a | pending | ready | blocked
+status: ready | active | blocked | completed | superseded
+phase: intake | analysis | plan | build | verify | review | security | lessons | commit
+ledger: <path>
+```
+
+Reuse this state for normal follow-ups. Start over only when the user explicitly resets it or introduces a materially different outcome.
+
+## Availability check
+
+Before declaring the task ready:
+
+- Confirm the chosen skill appears in the active runtime's discovered skill inventory.
+- Confirm any required tool or agent exists before dispatch.
+- Call `auto_runtime_status` and record the exact optional capabilities that are available now.
+- Confirm the repository exists for work types 2–6.
+- For work types 2–6, load `codegraph-first`, verify the CLI, initialize `.codegraph/` if needed, and record `codegraph: ready` before source work.
+- If a repository is missing, ask for its path; do not create or guess one.
+- If a skill family is absent, offer installation instructions or a supported family. Never silently substitute while retaining the unavailable family's name.

package/skills/auto-mode-router/references/models-and-tools.md

@@ -0,0 +1,74 @@
+# Models, agents, and tools
+
+## Live A/B/C/D routing
+
+`auto_model_route` builds its catalog from the active runtime every time it is called: Pi uses scoped or authenticated available models, while OMP uses `ctx.models.list()`. Exact versions come from that live registry, not this document.
+
+| Stage | Purpose | Eligible live groups | Normal agent and tools |
+|---|---|---|---|
+| A | Thinking/discovery | Claude Fable/Opus; OpenAI Astra/Sol; current Grok 4.6-or-newer | strategy skill; detected CodeGraph/LSP/AST tools, web for current facts; no implementation writes |
+| C | Plan second-eye | Same frontier pool, excluding A's underlying model | independent reviewer; plan, decisions, risks, read-only evidence; optional detected watcher |
+| B | Plan execution/coding | Claude Sonnet; OpenAI Terra/Luna/Codex-class; Cursor Composer; zero-metered Cursor/Devin routes; native Devin SWE; external Devin | builder/debugger method; detected code intelligence, tests, shell, and bounded task fan-out |
+| D | Implementation/code second-eye | Same execution pool, excluding B's underlying model | detected review command or independent reviewer; diff, impact, contracts, tests/scanners, no fixes |
+
+The extension compares normalized provider-independent identities, so the same model reached through Cursor and a direct provider still counts as the same choice. Prefer a different provider family as well when practical.
+
+OMP stage agents and the sequential Pi flow both inherit the model activated in the main session. Before each stage, call `auto_model_route` with `action: activate`; never assume the model remained selected after a manual model change.
+
+Intake and lessons use the runtime's inexpensive/default model when configured. Native `devin/swe-*` entries are ordinary runtime models. A separate external Devin option appears only when a Devin tool is detected and returns a delegation instruction.
+
+## Cross-family review
+
+Prefer a reviewer from a different model family than the main implementer when risk or change size justifies it:
+
+```text
+Codex builds ──► Claude reviews
+Claude builds ─► Codex reviews
+Cursor/Grok builds ─► strongest available Claude or Codex reviews
+```
+
+This is a model separation, not a second workflow spine.
+
+## Multi-agent use
+
+Use multiple agents only when tasks are independently writable or purely read-only.
+
+- Parallelize repository exploration, research, and independent reviews.
+- For implementation, define file ownership and dependencies first.
+- Prefer isolated worktrees for parallel writes.
+- Integrate and verify each result against the advancing canonical tree.
+- Fall back to serial work after repeated collisions or broad overlapping edits.
+- Never use a swarm merely to make a small task look more sophisticated.
+
+On OMP, `workflowz` and `orchestrate` may request native multi-agent behavior. On Pi, parallel work requires a compatible detected task/subagent extension. Neither route overrides the primary skill spine, model separation, evidence ledger, or approval gates.
+
+## Native runtime gates
+
+Call `auto_runtime_status` during intake. Follow [native-omp-runtime.md](native-omp-runtime.md) for OMP or [native-pi-runtime.md](native-pi-runtime.md) for Pi.
+
+- Any advisor/watcher is supplemental and read-only; C/D remain required when their stage applies.
+- Checkpoint/rewind may wrap disposable exploration only when the detected runtime documents those semantics.
+- `auto-qa` runs after B and before D for affected browser/desktop flows or artifact inspection.
+- A detected `security_scan` is used only when relevant; otherwise record the scanner/reviewer fallback.
+- Detected memory recall/retain is used only after the context retention decision.
+- A local commit is offered after acceptance, D, and required security gates pass; it never includes push.
+
+## Tool recommendations
+
+- Repository understanding: CodeGraph MCP/CLI is the authority for architecture, flows, candidate scope, and impact on work types 2–6 when available. Detected LSP handles exact symbols/types/renames/diagnostics; detected AST tools handle bounded structural queries or previewable rewrites. If CodeGraph is unavailable, record repository-wide impact as not verified rather than replacing it with a broad text crawl.
+- Verification: the repository's own tests, type checker, linter, formatter, build, and browser/simulator tools when relevant.
+- Bug discovery: detected DAP/debug tooling for supported live runtime failures, browser/desktop QA for user flows, and static/test evidence for backend or library code.
+- Security: detected `security_scan` when available, otherwise repository-native dependency audit, secret scan, SAST rules, configuration review, and source-to-sink inspection. Validate findings before changing code.
+- Current business/market facts: web research with source links; keep external posting disabled until approved.
+
+## Provider recommendation for the user's accounts
+
+- Cursor Composer or a zero-metered Cursor route: economical B/D work when present in the live catalog.
+- Claude Fable/Opus: A/C product thinking, architecture, specification, and cross-family review.
+- Claude Sonnet: B/D mid-layer implementation or review.
+- OpenAI Astra/Sol: A/C complex discovery and plan review.
+- OpenAI Terra/Luna/Codex-class: B/D implementation and review, chosen by task risk and cost.
+- Latest matching Grok 4.6-or-newer model: A/C independent frontier analysis or current web/social context.
+- Native Devin SWE: B/D when exposed by the runtime. External Devin: bounded delegation with acceptance criteria and a quota limit.
+
+Use Pi or OMP's own authentication and model UI as the authority for what the account can actually access.

package/skills/auto-mode-router/references/native-omp-runtime.md

@@ -0,0 +1,88 @@
+# Native OMP runtime integration
+
+Use this reference after `auto_runtime_status` reports what the active OMP session actually exposes. Optional native features must degrade cleanly; never claim a gated tool ran when it was unavailable.
+
+## Workflow shape
+
+```text
+A discovery ──► C independent plan review ──► plan gate
+                                               │
+                                               ▼
+                                     B implementation
+                                               │
+                                               ▼
+                                   conditional verification
+                                  tests · DAP · browser/desktop
+                                               │
+                                               ▼
+                                      D code review
+                                               │
+                                               ▼
+                                 conditional security review
+                                               │
+                                               ▼
+                               lessons/memory ──► optional commit
+```
+
+The A/B/C/D models remain the authoritative separation contract. Native OMP features strengthen those stages; they do not silently replace or skip them.
+
+## Advisor
+
+The native advisor is an optional continuous watcher, not approval authority and not a replacement for the final C or D verdict.
+
+- Offer it when the `advisor` command is present and the user accepts its extra model usage.
+- Use a different underlying model family from the active A or B model when practical.
+- Keep advisor tools read-only. Prefer `read` and `lsp`; do not grant `write`, `edit`, `bash`, or `eval` merely for convenience.
+- Use `/advisor configure` to set project/user `WATCHDOG.yml`, `/advisor on` to enable it for the session, and `/advisor status` to verify the actual model and usage.
+- Do not silently rewrite the user's global `modelRoles.advisor` or existing `WATCHDOG.yml`.
+
+## Deterministic and parallel execution
+
+`workflowz` is an explicit user prompt control for a deterministic multi-agent workflow. `orchestrate` is appropriate for substantial independent work whose decomposition is less fixed. The normal Auto Mode path may call `task` directly without either keyword.
+
+For `task` fan-out:
+
+1. Prove the units are independent or read-only.
+2. Give the batch shared acceptance criteria and narrow per-item ownership.
+3. Use isolated worktrees for parallel writes when available.
+4. Require structured findings or patch/test evidence.
+5. Integrate into one canonical tree and rerun the affected checks before D.
+
+Use serial execution for a small change or overlapping files. A swarm is a scaling option, not a mandatory stage.
+
+## Checkpoint and rewind
+
+These tools prune disposable conversation exploration; they are not filesystem snapshots or generic stage markers.
+
+- Use one checkpoint before a long research/debug branch whose raw transcript is not needed later.
+- End it with exactly one rewind containing a concise evidence report.
+- Never nest checkpoints.
+- Do not rewind away an unresolved approval, security finding, required decision, or unrecorded acceptance evidence.
+- If either tool is unavailable, continue normally and use the Markdown ledger for durable state.
+
+## Verification routing
+
+- Every implementation: focused tests, type checks, lint/build as applicable.
+- Known or reproducible runtime defect: native DAP `debug` when supported.
+- Web UI: browser helpers through `eval`; test first use, primary flow, invalid input, and dependency failure when relevant.
+- Native desktop UI: computer helpers through `eval` when enabled.
+- Type 5 or high-risk auth/secrets/money/personal-data changes: native `security_scan` when available, otherwise repository-native scanners plus `auto-security-reviewer`.
+- D review: prefer OMP `/review`; use `auto-reviewer` read-only `task` fan-out when `/review` is unavailable or the workflow needs its recorded stage model.
+
+Record each skipped or unavailable verification surface as `not verified` with its consequence.
+
+## Memory and lessons
+
+Prefer OMP's native memory backend over a separate ad-hoc MCP integration.
+
+- Hindsight requires `memory.backend: hindsight`, a reachable service, and any token through `HINDSIGHT_API_TOKEN` or the user's secure OMP configuration.
+- Use per-project isolation for client/employer repositories. Job/client retention remains off until policy permits it.
+- Treat recalled memory as heuristic. Verify it against current repository evidence.
+- At close, write `lessons.md` first. Then use `learn`/`retain` only when those tools are available and retention is approved.
+- Never retain secrets, credentials, raw client data, personal data, or unvalidated hypotheses.
+
+## Commit, sharing, and publication
+
+- After D passes and acceptance evidence is complete, offer `omp commit` to create atomic commits. Do not push as part of that step.
+- Push, PR creation, main push, merge, deployments, messages, and other web publication remain protected actions.
+- `/collab` and `/share` are off by default and require one-use `post-web` approval. For job/client work, confirm the participant and use view-only unless write access is explicitly needed.