@fiale-plus/pi-rogue-advisor 0.1.3 → 0.1.5

package/README.md

@@ -1,14 +1,50 @@
 # @fiale-plus/pi-rogue-advisor
 
-PiRogue advisor: session coaching, phase-aware routing, mid-hour check-ins, and decision framing for Pi.
+## What this package is
 
-The bundled binary gate model is shipped with the package and auto-seeded on install.
+Strategic advisor for Pi sessions with low-overhead preflight/post-review routing, model auto-detection, session memory, and optional mid-session check-ins.
 
-Install locally from this repo root: `npm install`
+- SOTA-first model fallback: `gpt-5.5`/`claude-opus-4-6`/`claude-sonnet-4-6` where available.
+- Keeps command-level behavior simple and explicit.
 
-Published install: `pi install @fiale-plus/pi-rogue-advisor`
+## Install
 
-Useful commands:
+```bash
+# Published package (recommended)
+pi install npm:@fiale-plus/pi-rogue-advisor
+
+# Local package development
+npm install --workspace packages/advisor
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/pi-rogue` | Show the Pi-Rogue cockpit + command pointers |
+| `/advisor` | Show status (`/advisor status`) and quick hint |
+| `/advisor status` | Show mode, review policy, check-in status, model selection, counters |
+| `/advisor on` | Enable advisor (auto mode) |
+| `/advisor off` | Disable advisor |
+| `/advisor mode auto\|manual\|off` | Change routing behavior |
+| `/advisor review light\|strict\|off` | Change review strictness |
+| `/advisor checkins on\|off\|<minutes>` | Enable/disable low-cost mid-hour check-ins |
+| `/advisor config` | Show current config |
+| `/advisor model <provider>/<model>` | Set explicit model override |
+| `/advisor <question>` | Get one-shot advisory response |
+
+## Notes on defaults
+
+- `mode`: `auto`
+- `review`: `light`
+- `checkins`: `mid-hour`
+- `checkinIntervalMinutes`: `30`
+- `model`: not set (auto-detected)
+
+Check-ins gate on session activity, are bounded, and avoid overlapping calls.
+
+## Stability guarantees
+
+- No flattening: the advisor remains its own surface and does not hide orchestration commands.
+- Cockpit is simple and explicit: `/pi-rogue` is the top-level status view.
 
-- `/pi-rogue` — cockpit/status entry point
-- `/advisor checkins on|off|<minutes>` — configure low-power mid-session check-ins

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fiale-plus/pi-rogue-advisor",
-  "version": "0.1.3",
-  "description": "PiRogue advisor extension for Pi — multi-model support, SOTA model suggestion, cache-aware session advisory.",
+  "version": "0.1.5",
+  "description": "Pi-Rogue advisor extension for Pi — multi-model support, SOTA model suggestion, cache-aware session advisory.",
   "type": "module",
   "license": "MIT",
   "repository": {

package/skills/advisor/SKILL.md

@@ -3,48 +3,46 @@ name: advisor
 description: Zero-config strategic advisor for Pi. Auto-detects best model, phase-aware routing, preflight + post-review + cache. Use for architecture, tradeoffs, planning.
 ---
 
-# PiRogue Advisor
+# Pi-Rogue Advisor
 
-Works out of the box. Just install and use `/advisor` or `/pi-rogue`.
-
-> 96 strategic calls saved ~$53 on GPT-5.5 over 3,071 turns — see [`docs/savings.md`](../../docs/savings.md)
+Use this skill for non-trivial decisions before/after significant edits.
 
 ## Quick start
 
-- `/pi-rogue` — cockpit/status entry point
-- `/advisor` — status + config
-- `/advisor <question>` — get immediate advice
-- `/advisor on|off` — enable/disable
-- `/advisor checkins on|off|<minutes>` — configure low-power mid-hour check-ins
-
-Zero config needed. Falls back through SOTA models (gpt-5.5 → claude-opus-4-6 → sonnet-4-6) automatically.
-
-The router is phase-aware: it keeps tiny edits cheap, escalates complex/high-risk work to SOTA, and writes compact routing logs for future classifier training.
-
-## When to call
-
-Agent should call `advisor` tool before: new frameworks, refactoring, API design, concurrency, security, tradeoffs.
-Skip: reads, small edits, one-liners.
+- `/pi-rogue` — open cockpit and command pointers
+- `/advisor status` — show current advisor settings and model route
+- `/advisor <question>` — ask immediate advice
+- `/advisor checkins on|off|<minutes>` — control low-power check-ins
 
-## Commands
+## Command surface
 
 | Command | What it does |
-|---------|-------------|
-| `/advisor` | Show status, config, cached note |
-| `/advisor <question>` | Get immediate strategic advice |
-| `/advisor on` | Enable auto mode (preflight+post+cache) |
-| `/advisor off` | Disable |
-| `/advisor mode auto\|manual\|off` | Set advisor mode |
-| `/advisor model <provider/model>` | Set specific model (e.g. `openai-codex/gpt-5.5`) |
-| `/advisor status` | Full status with model and check-in info |
-| `/advisor config` | Show current config |
-| `/advisor review light\|strict\|off` | Set review aggressiveness |
-| `/advisor checkins on\|off\|<minutes>` | Configure low-power mid-hour check-ins |
-
-## Config (5 fields, all optional)
-
-Defaults: `mode: auto, review: light, checkins: mid-hour, checkinIntervalMinutes: 30`
-
-```json
-{ "mode": "auto", "review": "light", "checkins": "mid-hour", "checkinIntervalMinutes": 30 }
-```
+|---|---|
+| `/advisor` | Show status + config summary |
+| `/advisor status` | Same as `/advisor` |
+| `/advisor on` | Enable auto mode |
+| `/advisor off` | Disable advisor |
+| `/advisor mode auto\|manual\|off` | Control when advisor auto-runs |
+| `/advisor review light\|strict\|off` | Set review threshold |
+| `/advisor checkins on\|off\|<minutes>` | Configure interval check-ins |
+| `/advisor config` | Dump full config |
+| `/advisor model <provider/model>` | Pin model explicitly |
+| `/advisor <question>` | Run one advisory response |
+
+## Routing and safety
+
+- Preflight is heuristics + quick local gate first.
+- Review runs after edits and/or at completion points by policy.
+- No hidden long-running background daemon: check-ins are interval-gated and lightweight.
+
+## Keep scope clear
+
+The advisor surface is separate from orchestration (`goal`/`loop`/`autoresearch`) and intentionally stays a small command set with explicit entries above.
+
+## Defaults
+
+- `mode: auto`
+- `review: light`
+- `checkins: mid-hour`
+- `checkinIntervalMinutes: 30`
+- `model: auto`

package/src/completions.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { advisorArgumentCompletions, piRogueArgumentCompletions } from "./completions.js";
+
+describe("advisor completions", () => {
+  it("offers top-level advisor continuations", () => {
+    const values = advisorArgumentCompletions("")?.map((i) => i.value);
+    expect(values).toEqual(expect.arrayContaining(["status", "config", "checkins", "review"]));
+  });
+
+  it("offers nested review choices", () => {
+    const values = advisorArgumentCompletions("review ")?.map((i) => i.value);
+    expect(values).toEqual(["light", "strict", "off"]);
+  });
+
+  it("offers check-in choices", () => {
+    const values = advisorArgumentCompletions("checkins ")?.map((i) => i.value);
+    expect(values).toEqual(expect.arrayContaining(["on", "off", "30", "60"]));
+  });
+});
+
+describe("pi-rogue cockpit completions", () => {
+  it("offers umbrella sections", () => {
+    const values = piRogueArgumentCompletions("")?.map((i) => i.value);
+    expect(values).toEqual(expect.arrayContaining(["status", "advisor", "orchestration", "help"]));
+  });
+
+  it("fans out to orchestration shortcuts", () => {
+    const values = piRogueArgumentCompletions("orchestration ")?.map((i) => i.value);
+    expect(values).toEqual(expect.arrayContaining(["goal", "loop", "autoresearch", "autoresearch-lab"]));
+  });
+});

package/src/completions.ts

@@ -0,0 +1,83 @@
+type CompletionItem = { value: string; label: string; description?: string };
+
+function item(value: string, description?: string): CompletionItem {
+  return { value, label: value, ...(description ? { description } : {}) };
+}
+
+function complete(values: Array<[string, string?]>, prefix: string): CompletionItem[] | null {
+  const q = prefix.trimStart().toLowerCase();
+  const items = values.map(([value, description]) => item(value, description));
+  const filtered = q
+    ? items.filter((i) => i.value.startsWith(q))
+    : items;
+  return filtered.length > 0 ? filtered : null;
+}
+
+function completionsForPrefix(prefix: string, topLevel: Array<[string, string?]>, nested: Record<string, Array<[string, string?]>>): CompletionItem[] | null {
+  const q = prefix.trimStart().toLowerCase();
+  if (!q) return complete(topLevel, q);
+
+  const [head, ...rest] = q.split(/\s+/);
+  if (!head) return complete(topLevel, q);
+
+  if (rest.length === 0) {
+    const top = complete(topLevel, head);
+    if (top) return top;
+  }
+
+  const next = nested[head];
+  if (next) {
+    return complete(next, rest.join(" "));
+  }
+
+  return complete(topLevel, q);
+}
+
+const advisorTopLevel: Array<[string, string?]> = [
+  ["status", "show status and configuration"],
+  ["config", "show full config"],
+  ["on", "enable auto mode"],
+  ["off", "disable advisor"],
+  ["mode", "set auto/manual/off"],
+  ["review", "set light/strict/off"],
+  ["checkins", "configure mid-hour check-ins"],
+  ["checkin", "alias for checkins"],
+  ["model", "set or inspect model override"],
+];
+
+const advisorNested: Record<string, Array<[string, string?]>> = {
+  mode: [["auto"], ["manual"], ["off"]],
+  review: [["light"], ["strict"], ["off"]],
+  checkins: [["on"], ["off"], ["10"], ["15"], ["30"], ["60"]],
+  checkin: [["on"], ["off"], ["10"], ["15"], ["30"], ["60"]],
+  model: [["auto"], ["openai-codex/gpt-5.5"], ["anthropic/claude-opus-4-6"]],
+};
+
+const piRogueTopLevel: Array<[string, string?]> = [
+  ["status", "show cockpit"],
+  ["advisor", "advisor status and check-ins"],
+  ["orchestration", "goal/loop/autoresearch shortcuts"],
+  ["checkins", "advisor check-ins"],
+  ["help", "show cockpit help"],
+];
+
+const piRogueNested: Record<string, Array<[string, string?]>> = {
+  advisor: advisorTopLevel,
+  orchestration: [
+    ["goal", "goal commands"],
+    ["loop", "loop commands"],
+    ["autoresearch", "solo research flow"],
+    ["autoresearch-lab", "parallel research flow"],
+    ["status", "show all surfaces"],
+  ],
+  checkins: advisorNested.checkins,
+  help: [["advisor"], ["orchestration"], ["checkins"], ["status"]],
+};
+
+export function advisorArgumentCompletions(prefix: string): CompletionItem[] | null {
+  return completionsForPrefix(prefix, advisorTopLevel, advisorNested);
+}
+
+export function piRogueArgumentCompletions(prefix: string): CompletionItem[] | null {
+  return completionsForPrefix(prefix, piRogueTopLevel, piRogueNested);
+}

package/src/extension.ts

@@ -5,6 +5,7 @@ import { Box, Text } from "@earendil-works/pi-tui";
 import { completeSimple, type ThinkingLevel } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { featureFile, readText, truncate, writeText } from "./internal.js";
+import { advisorArgumentCompletions, piRogueArgumentCompletions } from "./completions.js";
 import {
   appendRouteLog,
   binaryGatePredict,
@@ -373,7 +374,7 @@ function syncCheckinTimer(pi: ExtensionAPI, ctx: any): void {
 function piRogueCockpitText(config: AdvisorConfig, state: SessionState, currentNote: string): string {
   const normalized = normalizeAdvisorConfig(config);
   return [
-    "☠︎ PiRogue cockpit",
+    "☠︎ Pi-Rogue cockpit",
     currentNote ? `Advisor: ${truncate(currentNote, 220)}` : "Advisor: no current note",
     `Mode: ${normalized.mode} | Review: ${normalized.review} | Check-ins: ${normalized.checkins === "off" ? "off" : `${normalized.checkinIntervalMinutes}m`}`,
     `Turns: ${state.turns} | Advisor calls: ${state.advisorCalls} | Cache hits: ${state.cacheHits}`,
@@ -665,11 +666,49 @@ export function registerAdvisor(pi: ExtensionAPI): void {
 
   // ── /pi-rogue cockpit ──────────────────────────────────────────────────
   pi.registerCommand("pi-rogue", {
-    description: "Show PiRogue cockpit: advisor, check-ins, and orchestration command pointers",
-    handler: async (_args, ctx) => {
+    description: "Show Pi-Rogue cockpit: advisor, check-ins, and orchestration command pointers",
+    getArgumentCompletions: (prefix: string) => piRogueArgumentCompletions(prefix),
+    handler: async (args, ctx) => {
       const cfg = loadConfig();
       const state = loadState();
+      const arg = String(args ?? "").trim().toLowerCase();
       setPiRogueStatus(ctx, cfg, state);
+
+      if (!arg || arg === "status" || arg === "help") {
+        ctx.ui.notify(piRogueCockpitText(cfg, state, readText(CURRENT_PATH).trim()), "info");
+        return;
+      }
+
+      if (arg.startsWith("advisor")) {
+        ctx.ui.notify([
+          "Advisor surface:",
+          "  /advisor status",
+          "  /advisor config",
+          "  /advisor checkins on|off|<minutes>",
+          "  /advisor <question>",
+        ].join("\n"), "info");
+        return;
+      }
+
+      if (arg.startsWith("orchestration")) {
+        ctx.ui.notify([
+          "Orchestration surface:",
+          "  /goal show|clear|list|set <text>",
+          "  /loop status|off|clear|stop|<interval> <instruction>",
+          "  /autoresearch status|clear|<instruction>",
+          "  /autoresearch-lab status|clear|<instruction>",
+        ].join("\n"), "info");
+        return;
+      }
+
+      if (arg.startsWith("checkins")) {
+        ctx.ui.notify([
+          `Advisor check-ins: ${cfg.checkins === "off" ? "off" : `${cfg.checkinIntervalMinutes}m`}`,
+          "Use /advisor checkins on|off|<minutes> to change it.",
+        ].join("\n"), "info");
+        return;
+      }
+
       ctx.ui.notify(piRogueCockpitText(cfg, state, readText(CURRENT_PATH).trim()), "info");
     },
   });
@@ -677,6 +716,7 @@ export function registerAdvisor(pi: ExtensionAPI): void {
   // ── /advisor command ───────────────────────────────────────────────────
   pi.registerCommand("advisor", {
     description: "Senior engineering advisor. Usage: /advisor [on|off|status|config|question]",
+    getArgumentCompletions: (prefix: string) => advisorArgumentCompletions(prefix),
     handler: async (args, ctx) => {
       const a = String(args ?? "").trim().toLowerCase();
       const [cmd, ...rest] = a.split(/\s+/);