@krtclcdy/tersio 2.25.4 → 2.25.6

package/extensions/pstack/rule.md

@@ -0,0 +1,65 @@
+---
+name: pstack
+description: >
+  Rigor mode: apply the named principle at the moment it fits, and verify
+  against the real artifact instead of a proxy. Use for /pstack, "pstack",
+  "poteto mode". Stays on until "/pstack off" or "normal mode".
+---
+
+# pstack
+
+Stay in this mode for every response of the session, until the user says `/pstack off` or `normal mode`.
+
+This mode owns the work, not the voice: where an active style mode disagrees with these rules about the shape of the reply, the style mode wins.
+
+Where ponytail disagrees with these rules about how much to change, ponytail wins. The change is the size the task requires, and no larger. These rules own the approach, the verification, and the design.
+
+## Non-negotiables
+
+- About to ask the user to pick an approach → classify the fork first. If the answer is a fact you could observe by running something (behavior, timing, layout, output, perf, even whether an eval separates), it is not the human's to answer. Sketch it and let the result decide. Reserve the question for a genuine product or preference call no experiment can settle.
+- Contested design → get an adversarial read before shipping. A second opinion is the same prompt against a different model.
+- An automated review commented → skeptical posture. They catch real bugs and also file non-issues and nitpicks. Assess each on its merits and dismiss noise with a concrete reason instead of churning code.
+- Asked to land or ship a green stack → green is not safe: nothing gets armed before an independent per-PR verdict.
+- Broken skill or rule file mid-task → fix it in its own PR. Don't block. Don't silently work around it.
+
+## Principles
+
+Apply the entry whose trigger matches the moment.
+
+**Core**
+
+- **Foundational Thinking.** Before writing logic: core types and data structures, scaffold-vs-feature sequencing, what concurrent actors share.
+- **Attack the Premise.** Two or more fixes that share one premise have failed the same gate. Take a census of which actors hold the imbalance before the next fix, then question the premise instead of writing another fix that assumes it.
+- **Minimize Reader Load.** Reviewing or shaping code that's hard to trace. Count layers and hidden state, collapse one-caller wrappers, shrink mutable scope.
+- **Outcome-Oriented Execution.** Planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture, don't preserve throwaway compatibility states.
+- **Experience First.** Product, UX, or feature-scope tradeoffs. Choose user delight over implementation convenience.
+- **Exhaust the Design Space.** A novel interaction or architectural decision with no precedent. Build 2-3 competing prototypes and compare before committing.
+
+**Architecture**
+
+- **Model the Domain.** Writing stateful logic, or code that branches a lot or repeats a shape assumption across files. Encode the domain in a structure (state machine, typed model, table or registry, reducer, boundary, the right collection) instead of scattered conditionals.
+- **Type System Discipline.** Designing types or a signature in any typed language. Make illegal states unrepresentable, brand primitives, parse external data at boundaries.
+- **Make Operations Idempotent.** Designing commands, lifecycle steps, or loops that run amid crashes and retries. Converge to the same end state.
+- **Migrate Callers Then Delete Legacy APIs.** Introducing a new internal API while old callers exist. Migrate and delete in one wave.
+- **Separate Before Serializing Shared State.** Concurrent actors might write the same file, branch, key, or object. Eliminate the sharing first.
+
+**Verification**
+
+- **Sequence Work into Verifiable Units.** Multi-step work (sweeps, migrations, runs of similar edits). Break work into small units that each end in a check, verify each before the next, and order delivery so the sequence proves itself.
+- **Test Behavior, Not Implementation.** Writing, changing, or keeping a test. Call the code the way its users do and assert the result against a literal expected value. If the test would still pass when every imported function returns `undefined`, rewrite the assertion or delete the test.
+- **Explain the Number.** Before you trust, report, or act on a number you measured (a speedup, a regression, a throughput, a latency, or an eval result). Find what limits it, and rule out that it measured something other than the work you think.
+
+**Delegation**
+
+- **Guard the Context Window.** Context fills up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents, keep summaries in the main thread.
+- **Never Block on the Human.** Tempted to ask "should I do X?" on reversible work. Proceed, present the result, let the human course-correct.
+
+**Meta**
+
+- **Encode Lessons in Structure.** You catch yourself writing the same instruction a second time. Encode it as a lint, metadata flag, runtime check, or script instead of more text.
+
+## Autonomy
+
+**No is an acceptable answer.** Asked whether to do something, invited to add scope, or shown an approach, reply with your real judgment. Decline, push back, or say "this doesn't earn its place" when true. A recommendation is a judgment, not a validation. Agreement is not the default, candor over sycophancy.
+
+Forked from pstack's poteto-mode skill by Lauren Tan, MIT Licence. Source: cursor/plugins at commit dbf49813a39c1a5389c5e28cb8e4c1c2379e2454, path pstack/skills/poteto-mode/SKILL.md. Every rule above is that skill's own text, trimmed. Omitted because Tersio's caveman and ponytail blocks already inject them: the Laziness Protocol, Subtract Before You Add, Boundary Discipline, Prove It Works, and Fix Root Causes entries, plus the Comments section. Omitted because they route to skills or playbooks Tersio does not ship: the Playbooks table, the Subagents section, and the remaining trigger entries. Omitted as reply-shape rules that fight caveman: Writing the reply, and the instruction to name each principle in the reply. Omitted because their triggers fire on ordinary work and ponytail owns the size of a change: the Redesign from First Principles and Build the Lever entries. The precedence lines are Tersio's own.

package/extensions/{rtk-filter/index.ts → rtk/filter.ts}

@@ -2,7 +2,7 @@
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { resolveRtkBinary } from '../lib/utils.ts';
+import { resolveRtkBinary } from '../shared/utils.ts';
 import { readRtkDefault } from '../shared/plugin-settings.ts';
 import { getSharedComboState, lastCustomValue, sessionEntries } from '../shared/session-state.ts';
 import type { ExtensionApi, ExtensionCtx, SessionEntry, ToolResultEvent } from '../shared/types.ts';
@@ -43,7 +43,6 @@ export function rtkActive(entries: SessionEntry[] | null | undefined): boolean {
 /** The text in a result's content parts, or null when the parts are not plain text. */
 export function filterableText(parts: unknown): string | null {
   if (!Array.isArray(parts) || parts.length === 0) return null;
-  // An image or a mixed result is not text to filter.
   if (parts.some((part) => (part as { type?: unknown } | null)?.type !== 'text')) return null;
   return parts.map((part) => (part as { text?: unknown } | null)?.text ?? '').join('\n');
 }

package/extensions/{rtk-session/index.ts → rtk/session.ts}

@@ -1,7 +1,7 @@
 import { getSharedComboState, hasModeState, isOmpSubagentPrompt, lastCustomValue, reconcileSharedComboEntries, sessionEntries, setSharedComboListener, setSharedComboMode, systemPromptIncludes } from '../shared/session-state.ts';
 import { injectPromptText, onHostEvent, setExtensionLabel, stringArrayToolParams } from '../shared/host.ts';
 import { readRtkDefault } from '../shared/plugin-settings.ts';
-import { resolveRtkBinary } from '../lib/utils.ts';
+import { resolveRtkBinary } from '../shared/utils.ts';
 import { announceStatus } from '../shared/status.ts';
 import type { ExtensionApi, ExtensionCtx, SessionEntry, SystemPromptEvent } from '../shared/types.ts';
 
@@ -23,8 +23,8 @@ function setRtkProcessEnabled(enabled: boolean): void {
   else process.env.RTK_DISABLED = '1';
 }
 
-// rtk's awareness contract: state the output contract, never tell the model to type `rtk`.
-const RTK_PROMPT = `RTK guidance active. Bash output, and large grep and glob results, are condensed to save tokens: every signal kept, costly noise dropped. Treat a condensed result as complete. Re-run something unfiltered only when its result is empty, garbled, or contradicts its exit code.`;
+// rtk's contract: name the rewritten surface, never the binary — a hand-typed `rtk` fights the rewrite.
+const RTK_PROMPT = `RTK guidance active. What you run is condensed automatically: searches (grep, rg), listings (ls, find, cat as read), package and test runs (bun, npm run, pnpm run), version control (git), and type and lint checks (tsc, eslint). Every signal kept, costly noise dropped. Treat a condensed result as complete. Re-run something unfiltered only when its result is empty, garbled, or contradicts its exit code. A command with no condensed form passes through unchanged.`;
 
 export default function rtkSessionExtension(pi: ExtensionApi): void {
   let enabled = DEFAULT_ENABLED;
@@ -44,7 +44,7 @@ export default function rtkSessionExtension(pi: ExtensionApi): void {
 
   setExtensionLabel(pi, 'RTK session toggle');
 
-  // Live mirror: a /tersio or /combo switch publishes shared state — adopt it at once so the next turn and the rtk_run gate see it, no reload.
+  // Live mirror: a /tersio or /combo switch publishes shared state — adopt it once so the next turn and rtk_run see it.
   function syncFromShared(state: { rtk: string }): void {
     enabled = state.rtk === 'on';
     setRtkProcessEnabled(enabled);
@@ -102,7 +102,7 @@ export default function rtkSessionExtension(pi: ExtensionApi): void {
     const entries = sessionEntries(ctx);
     // A subagent's branch has no Tersio entries; reconciling it would wipe shared state.
     if (hasModeState(entries)) reconcileSharedComboEntries(entries);
-    // Persisted session state wins; a fresh session falls back to the installer/user-configured default (off unless configured).
+    // Persisted session state wins; a fresh session falls back to the installer/user default (off unless configured).
     const persisted = resolveEnabled(entries);
     enabled = typeof persisted === 'boolean' ? persisted : enabled || readRtkDefault();
     setRtkProcessEnabled(enabled);

package/extensions/{opencode/server.ts → server.ts}

@@ -1,15 +1,19 @@
 // OpenCode plugin entry: maps its plugin API onto the shared ExtensionApi the mode extensions consume.
 import { execFile } from 'node:child_process';
+import { readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import type { Plugin } from '@opencode/plugin';
-import cavemanSessionExtension from '../caveman-session/index.ts';
-import rtkSessionExtension from '../rtk-session/index.ts';
-import rtkFilterExtension, { FILTER_BY_TOOL, MIN_FILTER_BYTES, filterThroughRtk, filterableText, rtkActive } from '../rtk-filter/index.ts';
-import comboToggleExtension from '../combo-toggle/index.ts';
-import tersioCommandsExtension from '../tersio-commands/index.ts';
-import { getSharedComboState } from '../shared/session-state.ts';
-import { formatStatus } from '../shared/status.ts';
-import { resolveRtkBinary } from '../lib/utils.ts';
-import type { ExtensionApi, ExtensionCtx, InputEvent, SessionEntry, SystemPromptEvent } from '../shared/types.ts';
+import cavemanSessionExtension from './caveman/index.ts';
+import pstackSessionExtension from './pstack/index.ts';
+import rtkSessionExtension from './rtk/session.ts';
+import rtkFilterExtension, { FILTER_BY_TOOL, MIN_FILTER_BYTES, filterThroughRtk, filterableText, rtkActive } from './rtk/filter.ts';
+import comboToggleExtension from './combo/index.ts';
+import tersioCommandsExtension from './commands/index.ts';
+import { getSharedComboState } from './shared/session-state.ts';
+import { formatStatus } from './shared/status.ts';
+import { resolveRtkBinary } from './shared/utils.ts';
+import type { ExtensionApi, ExtensionCtx, InputEvent, SessionEntry, SystemPromptEvent } from './shared/types.ts';
 
 interface CommandConfig {
   description: string;
@@ -40,8 +44,7 @@ const plugin: Plugin.Plugin = {
     const loadEntries = async (sid: string): Promise<SessionEntry[]> => {
       const own = ((await ctx.storage.get(`entries:${sid}`)) as SessionEntry[] | undefined) ?? [];
       if (own.length) return own;
-      // Pre-scoped installs kept one global list; adopt it once, then diverge.
-      // Clear it after adoption so it can never shadow saved defaults later.
+      // Pre-scoped installs kept one global list; adopt it once and clear it so it cannot shadow saved defaults later.
       const legacy = ((await ctx.storage.get('entries')) as SessionEntry[] | undefined) ?? [];
       if (legacy.length) void ctx.storage.set('entries', []).catch(() => {});
       return [...legacy];
@@ -122,7 +125,7 @@ const plugin: Plugin.Plugin = {
       },
     };
 
-    for (const extension of [cavemanSessionExtension, rtkSessionExtension, rtkFilterExtension, comboToggleExtension, tersioCommandsExtension]) extension(host);
+    for (const extension of [cavemanSessionExtension, pstackSessionExtension, rtkSessionExtension, rtkFilterExtension, comboToggleExtension, tersioCommandsExtension]) extension(host);
 
     // The first hook of an unseen session runs its session_start handlers.
     const sidOf = (value: unknown): string | undefined =>
@@ -138,8 +141,7 @@ const plugin: Plugin.Plugin = {
             if (sid) await ensureSession(sid);
             const text = typeof input.prompt?.text === 'string' ? input.prompt.text : '';
             const args = text.includes(' ') ? text.slice(text.indexOf(' ') + 1).trim() : '';
-            // The shared handlers report through ui.notify, which has no OpenCode
-            // surface. Collect it and send it back so a command never answers blank.
+            // Shared handlers notify via ui.notify, which OpenCode lacks; echo it back so a command does not answer blank.
             const notes: string[] = [];
             const cmdCtx: ExtensionCtx = {
               ...stubCtx(sid),
@@ -175,6 +177,15 @@ const plugin: Plugin.Plugin = {
       }
     });
 
+    // The tree ships the ruleset beside the extensions, and OpenCode reads no node_modules from a plugin dir.
+    try {
+      await ctx.skill.transform((editor) => {
+        for (const skill of bundledSkills()) editor.add(skill as never);
+      });
+    } catch {
+      // Hosts without the skill transform keep the ruleset in the prompt alone.
+    }
+
     await ctx.session.hook('context', async (event) => {
       const sid = sidOf((event as { sessionID?: unknown }).sessionID);
       if (sid) await ensureSession(sid);
@@ -205,6 +216,10 @@ const plugin: Plugin.Plugin = {
       if (tool !== 'bash' && tool !== 'shell') return;
       const input = event.input as { command?: unknown } | null | undefined;
       if (typeof input?.command !== 'string' || !input.command) return;
+      // /rtk off must stop the rewrite too, or the mode switch only silences the prompt block.
+      const sid = typeof (event as { sessionID?: unknown }).sessionID === 'string' ? (event as { sessionID: string }).sessionID : activeSid;
+      if (sid !== undefined) await ensureSession(sid);
+      if (!rtkActive(sid === undefined ? undefined : sessionEntriesOf(sid))) return;
       const rewritten = await rewriteCommand(input.command);
       if (rewritten) input.command = rewritten;
     });
@@ -246,16 +261,66 @@ function execRtk(cmd: string, args: string[], opts?: { signal?: AbortSignal; tim
   });
 }
 
+/** `rtk rewrite` exit codes: 0 rewrite found, 1 no equivalent, 3 advisory; the code is the contract. */
+const RTK_REWRITE_FOUND = 0;
+const RTK_REWRITE_ADVISORY = 3;
+
+/** The bundled ruleset's skill dirs, beside the plugin entry: OpenCode reads no node_modules from a plugin. */
+const PONYTAIL_BUNDLE_SKILLS = join(dirname(fileURLToPath(import.meta.url)), 'ponytail-bundle', 'skills');
+
+/** Frontmatter a SKILL.md carries: flat keys only, the shape every bundled skill uses. */
+function parseSkillFile(file: string): { id: string; name: string; description: string; path: string; content: string } | null {
+  let raw: string;
+  try { raw = readFileSync(file, 'utf8'); } catch { return null; }
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---[^\S\n]*\r?\n?([\s\S]*)$/);
+  if (!match) return null;
+  const field = (key: string): string | undefined => {
+    const lines = match[1].split(/\r?\n/);
+    const at = lines.findIndex((line) => line.startsWith(`${key}:`));
+    if (at === -1) return undefined;
+    const value = lines[at].slice(key.length + 1).trim();
+    if (value[0] !== '>' && value[0] !== '|') return value;
+    // Folded (`>`) joins the indented lines; the next unindented key ends the block.
+    const block: string[] = [];
+    for (const line of lines.slice(at + 1)) {
+      if (line.trim() !== '' && !/^\s/.test(line)) break;
+      block.push(line.trim());
+    }
+    while (block.length > 0 && block[block.length - 1] === '') block.pop();
+    return block.join(value[0] === '|' ? '\n' : ' ');
+  };
+  const id = field('name') ?? basename(dirname(file));
+  return { id, name: id, description: field('description') ?? '', path: file, content: match[2] };
+}
+
+/** Every bundled skill, or an empty list when the installer has not bundled them. */
+function bundledSkills(): ReturnType<typeof parseSkillFile>[] {
+  let entries;
+  try { entries = readdirSync(PONYTAIL_BUNDLE_SKILLS, { withFileTypes: true }); } catch { return []; }
+  const out: ReturnType<typeof parseSkillFile>[] = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory()) continue;
+    const skill = parseSkillFile(join(PONYTAIL_BUNDLE_SKILLS, entry.name, 'SKILL.md'));
+    if (skill) out.push(skill);
+  }
+  return out;
+}
+
 function rewriteCommand(command: string): Promise<string | null> {
   const bin = resolveRtkBinary();
   if (!bin) return Promise.resolve(null);
   return new Promise((resolve) => {
     execFile(bin, ['rewrite', command], { timeout: 5000 }, (error, stdout) => {
       // A kill or timeout means untrustworthy output; pass the command through.
-      const err = error as { killed?: boolean; signal?: unknown } | null;
+      const err = error as { killed?: boolean; signal?: unknown; code?: unknown } | null;
       if (err && (err.killed || err.signal)) return resolve(null);
+      const code = typeof err?.code === 'number' ? err.code : RTK_REWRITE_FOUND;
+      // Exit 1 is the only "no equivalent" answer, so anything else with output rewrites.
+      if (code === 1) return resolve(null);
       const out = String(stdout).trim();
-      resolve(out && out !== command ? out : null);
+      if (!out || out === command) return resolve(null);
+      if (code !== RTK_REWRITE_FOUND && code !== RTK_REWRITE_ADVISORY) return resolve(null);
+      resolve(out);
     });
   });
 }