pi-native-output-styles 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.4.0
+
+Repackaged as `pi-native-output-styles` — a Pi-only output-style switcher built on Pi's native `.pi/` directories.
+
+### Added
+
+- Native `.pi/` locations. Styles resolve from `~/.pi/agent/output-styles/` and `<repo>/.pi/output-styles/`; `--save` / `--project` write `~/.pi/agent/output-styles.json` and `<repo>/.pi/output-styles.json`.
+- `PI_CODING_AGENT_DIR` is honoured as the user config root (default `~/.pi/agent`).
+
+### Changed
+
+- `/style` now injects a single `# Personality` block at the top of the system prompt, replacing the previous slot-swapping behaviour. It is idempotent and touches nothing else in the prompt.
+- Bundled styles are `concise`, `explanatory`, `teacher`, `reviewer`, `diagrams-first`, `ste`, `eli5`.
+
+### Removed
+
+- All non-Pi harness support: the `.omp/` style and state locations, the slot-replacement logic for `§`-delimited prompts, and the three `omp-*` bundled presets.
+- The CLI demo assets, which showed another harness.
+
+### Notes
+
+Forked from [`LoneExile/pi-output-styles`](https://github.com/LoneExile/pi-output-styles). Inherited changelog entries for versions before the fork are not reproduced here; see upstream for that history.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 LoneExile
+Copyright (c) 2026 code-koan contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# pi-native-output-styles
+
+[![CI](https://github.com/code-koan/pi-native-output-styles/actions/workflows/ci.yml/badge.svg)](https://github.com/code-koan/pi-native-output-styles/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/pi-native-output-styles.svg)](https://www.npmjs.com/package/pi-native-output-styles)
+[![license](https://img.shields.io/npm/l/pi-native-output-styles.svg)](./LICENSE)
+
+Named, swappable system-prompt styles for [Pi](https://pi.dev) — with a live `/style` switcher. Unlike Claude Code's output styles (which need `/clear` to switch), styles here apply and switch **live, mid-session**.
+
+Styles and saved defaults live in Pi's own directories: `~/.pi/agent/output-styles/` and `<repo>/.pi/output-styles/`.
+
+## Install
+
+```bash
+pi install npm:pi-native-output-styles
+
+# or straight from the repo
+pi install git:github.com/code-koan/pi-native-output-styles
+```
+
+Then start a **new** session. Extensions do not hot-reload.
+
+## Use
+
+- `/style` — show the active style and list the available ones.
+- `/style <name>` — activate a style for this session.
+- `/style <name> --save` — also save it as your personal (user) default.
+- `/style <name> --project` — save it as the project default (committed with the repo).
+- `/style off` — clear the active style for this session, overriding any saved default.
+- `/style off --save` / `/style off --project` — also clear the saved default. `none` is an alias for `off`.
+- While composing `/style`, a hint line below the input shows the available flags.
+
+The style is applied every turn, and the status line shows `style: eli5`.
+
+## How a style is applied
+
+Pi's assembled system prompt is flat prose plus XML blocks — there is no personality slot to replace. The active style is injected as a `# Personality` block at the **top** of the prompt, above the tool list and the cwd line, the way Claude Code output styles sit.
+
+It is idempotent: a prompt that already carries the marker is left untouched, so switching styles mid-session never stacks a second block. Nothing else in the prompt is modified.
+
+## Bundled styles
+
+`concise` · `explanatory` · `teacher` · `reviewer` · `diagrams-first` · `ste` · `eli5`
+
+`ste` writes in [ASD-STE100](https://asd-ste100.org) Simplified Technical English, with the v2.0 action-first reply shape for person-addressed replies, tasks, issues, pull request descriptions, and commit messages. Adapted from [Ege Chelebi's ste-writing skill](https://github.com/woosal1337/blog/blob/9240b25eac013467554fd8217f319743aa0282b8/videos/ep01-the-cure-for-ai-slop/asd-ste100/SKILL.md).
+
+`eli5` is [Lydia Hallie's ELI5 style](https://x.com/lydiahallie/status/2080378470111256907).
+
+## Custom styles
+
+Drop a Markdown file in either location. The filename is the style name unless frontmatter overrides it.
+
+- Project: `<repo>/.pi/output-styles/<name>.md`
+- Personal: `~/.pi/agent/output-styles/<name>.md`
+
+```markdown
+---
+name: teacher
+description: Teach as you go
+---
+Act as a patient teacher. Explain the concept before applying it.
+```
+
+The body becomes the `# Personality` block.
+
+Precedence:
+
+- **Definitions** (low → high): bundled < user < project.
+- **Which style is active**: session `/style` > user default > project default.
+
+## Config
+
+| | Path |
+| --- | --- |
+| Project styles | `<repo>/.pi/output-styles/` |
+| User styles | `~/.pi/agent/output-styles/` |
+| Project default (`--project`) | `<repo>/.pi/output-styles.json` |
+| User default (`--save`) | `~/.pi/agent/output-styles.json` |
+
+Environment:
+
+- `PI_CODING_AGENT_DIR` — Pi's config-dir override. Sets the user root (default `~/.pi/agent`).
+- `PI_OUTPUT_STYLES_HOME` — higher-precedence override of the user root, for tests and non-standard layouts.
+
+## Develop
+
+```bash
+bun install
+bun test
+bun x tsc --noEmit
+```
+
+## Credits
+
+Started as a fork of [LoneExile/pi-output-styles](https://github.com/LoneExile/pi-output-styles), reworked to use Pi's native `.pi/` directories. MIT licensed; original work © 2026 LoneExile.

package/extensions/output-styles.ts

@@ -0,0 +1,401 @@
+// pi-native-output-styles — named, swappable system-prompt styles for Pi.
+// The active style is injected as a `# Personality` block at the top of the
+// system prompt each turn. Pure helpers are exported for unit testing.
+
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface Style {
+  name: string;
+  description: string;
+  body: string;
+}
+
+type NotifyType = "info" | "warning" | "error";
+
+interface ExtensionUI {
+  setStatus(key: string, text: string | undefined): void;
+  setWidget(key: string, lines: string[] | undefined, options?: { placement: "aboveEditor" | "belowEditor" }): void;
+  getEditorText(): string;
+  notify(message: string, type?: NotifyType): void;
+}
+
+interface ExtensionContext {
+  cwd: string;
+  hasUI: boolean;
+  ui: ExtensionUI;
+  setInterval?(callback: () => void, ms?: number): unknown;
+}
+
+interface BeforeAgentStartEvent {
+  prompt: string;
+  systemPrompt: string;
+}
+
+interface BeforeAgentStartResult {
+  systemPrompt?: string;
+}
+
+interface AutocompleteItem {
+  value: string;
+  label: string;
+  description?: string;
+  hint?: string;
+}
+
+type EventHandler<E, R = void> = (event: E, ctx: ExtensionContext) => R | void | Promise<R | void>;
+
+interface ExtensionAPI {
+  on(event: "session_start", handler: EventHandler<unknown>): void;
+  on(event: "session_shutdown", handler: EventHandler<unknown>): void;
+  on(event: "before_agent_start", handler: EventHandler<BeforeAgentStartEvent, BeforeAgentStartResult>): void;
+  registerCommand(
+    name: string,
+    def: {
+      description: string;
+      getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null;
+      handler: (args: string, ctx: ExtensionContext) => void | Promise<void>;
+    },
+  ): void;
+}
+
+export function parseStyle(text: string, fallbackName: string): Style {
+  let name = fallbackName;
+  let description = "";
+  let body = text;
+  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)([\s\S]*)$/);
+  if (fm) {
+    body = fm[2];
+    for (const line of fm[1].split(/\r?\n/)) {
+      const m = line.match(/^([A-Za-z][\w-]*)\s*:\s*(.*)$/);
+      if (!m) continue;
+      const key = m[1].toLowerCase();
+      const value = m[2].trim().replace(/^(["'])([\s\S]*)\1$/, "$2");
+      if (key === "name" && value.length > 0) name = value;
+      else if (key === "description") description = value;
+    }
+  }
+  return { name, description, body: body.trim() };
+}
+
+export function discoverStyles(dirsLowToHigh: string[]): Map<string, Style> {
+  const styles = new Map<string, Style>();
+  for (const dir of dirsLowToHigh) {
+    let entries: string[];
+    try {
+      entries = readdirSync(dir).sort();
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".md")) continue;
+      let text: string;
+      try {
+        text = readFileSync(join(dir, entry), "utf8");
+      } catch {
+        continue;
+      }
+      const style = parseStyle(text, entry.slice(0, -3));
+      if (style.body.length === 0) continue;
+      styles.set(style.name, style);
+    }
+  }
+  return styles;
+}
+
+// Pi config roots: `PI_CODING_AGENT_DIR` (default `~/.pi/agent`) for user scope
+// and `<repo>/.pi` for project scope. `PI_OUTPUT_STYLES_HOME` overrides the
+// user root and takes precedence over `PI_CODING_AGENT_DIR`.
+export function configHome(): string {
+  return process.env.PI_OUTPUT_STYLES_HOME || process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+}
+
+export function userStylesDir(): string {
+  return join(configHome(), "output-styles");
+}
+
+export function projectStylesDir(cwd: string): string {
+  return join(cwd, ".pi", "output-styles");
+}
+
+export function bundledStylesDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "styles");
+}
+
+export interface StyleState {
+  active?: string;
+}
+
+export function readState(file: string): StyleState {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+    if (parsed && typeof parsed === "object" && "active" in parsed && typeof parsed.active === "string") {
+      return { active: parsed.active };
+    }
+  } catch {
+    // missing or malformed → empty
+  }
+  return {};
+}
+
+export function writeState(file: string, state: StyleState): void {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(state, null, 2) + "\n");
+}
+
+export function userStateFile(): string {
+  return join(configHome(), "output-styles.json");
+}
+
+export function projectStateFile(cwd: string): string {
+  return join(cwd, ".pi", "output-styles.json");
+}
+
+// Session selection beats the user default, which beats the project default.
+export function resolveActiveName(
+  sessionActive: string | null,
+  userState: StyleState,
+  projectState: StyleState,
+): string | null {
+  return sessionActive ?? userState.active ?? projectState.active ?? null;
+}
+
+const MARKER_PREFIX = "<!-- output-styles:";
+
+export function styleMarker(style: Style): string {
+  return `${MARKER_PREFIX}${style.name} -->\n${style.body}`;
+}
+
+// Pi's assembled system prompt is flat prose plus XML blocks — it has no
+// personality slot. So the style becomes one, prepended to the top the way
+// Claude Code output styles are, rather than appended after the tool list and
+// cwd line. Idempotent: a prompt that already carries a marker is returned as-is.
+export function applyStyle(systemPrompt: string, style: Style): string {
+  if (systemPrompt.includes(MARKER_PREFIX)) return systemPrompt;
+  const marked = styleMarker(style);
+  return systemPrompt.length === 0 ? marked : `# Personality\n${marked}\n\n${systemPrompt}`;
+}
+
+export type PersistScope = "none" | "user" | "project";
+
+export interface StyleCommandArgs {
+  name: string | null;
+  persist: PersistScope;
+}
+
+// Flags recognized by the /style command. parseStyleCommandArgs maps each to a
+// persist scope; the command handler warns on any --flag NOT in this set.
+// Keep this in sync with the flag handling in parseStyleCommandArgs.
+const KNOWN_FLAGS = ["--save", "--global", "--project"];
+
+// Reserved argument words that clear the active style instead of selecting one.
+const OFF_WORDS: Record<string, true> = { off: true, none: true };
+
+export function parseStyleCommandArgs(args: string): StyleCommandArgs {
+  const tokens = args.trim().split(/\s+/).filter(t => t.length > 0);
+  let name: string | null = null;
+  let save = false;
+  let project = false;
+  for (const t of tokens) {
+    if (t === "--save" || t === "--global") save = true;
+    else if (t === "--project") project = true;
+    else if (!t.startsWith("--") && name === null) name = t;
+  }
+  const persist: PersistScope = project ? "project" : save ? "user" : "none";
+  return { name, persist };
+}
+
+const STATUS_KEY = "output-styles";
+const HINT_KEY = "output-styles-hint";
+// Persistent ghost hint shown below the editor while a `/style` command is
+// being composed. Pi only renders inline usage ghost text for builtin
+// commands, so this widget carries the same message for extension commands.
+const STYLE_HINT_LINES = [
+  "/style <name|off> [--save] [--project]",
+  "persist: --save (user default, --global alias) · --project (this project)",
+];
+
+// Pure matcher for the widget: show the hint while the input starts with a
+// `/style` command word (line start, with optional leading whitespace).
+export function styleHintFor(text: string): string[] | null {
+  return /^\s*\/style(?:\s|$)/.test(text) ? STYLE_HINT_LINES : null;
+}
+
+// Poller state: one started flag guards re-registration across in-process
+// session restarts; lastHintInput dedupes widget updates against the text the
+// hint was computed for.
+let started = false;
+let lastHintInput: string | null = null;
+
+// Debounced poller: only updates the widget once the input text is stable
+// across a tick and differs from the last-checked text. Exported for tests.
+export function startHintPoller(ctx: ExtensionContext): void {
+  if (typeof ctx.setInterval !== "function") return;
+  let stableInput: string | null = null;
+  ctx.setInterval(() => {
+    const text = ctx.ui.getEditorText();
+    if (text !== stableInput) {
+      stableInput = text;
+      return;
+    }
+    const lines = styleHintFor(text);
+    if (lines !== null && lastHintInput !== text) {
+      ctx.ui.setWidget(HINT_KEY, lines, { placement: "belowEditor" });
+      lastHintInput = text;
+    } else if (lines === null && lastHintInput !== null) {
+      ctx.ui.setWidget(HINT_KEY, undefined);
+      lastHintInput = null;
+    }
+  }, 600);
+}
+
+// Session-active style selection is process-global (module-level) state.
+// This assumes one module instance per session/cwd, which holds under
+// today's per-session extension loading. If Pi ever shares one module
+// instance across multiple concurrent sessions, switch this to a
+// cwd-keyed Map instead of a single variable.
+type SessionSelection = { type: "inherit" } | { type: "off" } | { type: "style"; name: string };
+let session: SessionSelection = { type: "inherit" };
+
+function styleDirs(cwd: string): string[] {
+  // low → high precedence: bundled < user < project
+  return [bundledStylesDir(), userStylesDir(), projectStylesDir(cwd)];
+}
+
+// Argument completions for `/style <name>`: matches style names by prefix.
+// getArgumentCompletions carries no ctx, so discovery uses process.cwd() as the
+// project scope (best-effort; the command handler still uses ctx.cwd).
+// Flags advertised as dim ghost text on every completion item, so users see
+// that a style can be persisted beyond the session with --save (user default)
+// or --project (per-project default). --global is accepted as a --save alias.
+const FLAG_HINT = "[--save] [--project]";
+
+export function styleCompletions(argumentPrefix: string, cwd: string): AutocompleteItem[] | null {
+  if (argumentPrefix.includes(" ")) return null;
+  const prefix = argumentPrefix.trim().toLowerCase();
+  const styleItems: AutocompleteItem[] = [...discoverStyles(styleDirs(cwd)).values()]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(s => ({ value: s.name, label: s.name, description: s.description || undefined, hint: FLAG_HINT }));
+  const offItem: AutocompleteItem = {
+    value: "off",
+    label: "off",
+    description: "Turn off styling for this session",
+    hint: FLAG_HINT,
+  };
+  const items = [...styleItems, offItem].filter(i => i.value.toLowerCase().startsWith(prefix));
+  return items.length > 0 ? items : null;
+}
+
+export function resolveActiveStyle(cwd: string, styles?: Map<string, Style>): Style | null {
+  if (session.type === "off") return null;
+  const sessionActive = session.type === "style" ? session.name : null;
+  const name = resolveActiveName(sessionActive, readState(userStateFile()), readState(projectStateFile(cwd)));
+  if (!name) return null;
+  const map = styles ?? discoverStyles(styleDirs(cwd));
+  return map.get(name) ?? null;
+}
+
+function refreshStatus(ctx: ExtensionContext, style: Style | null): void {
+  if (!ctx.hasUI || typeof ctx.ui.setStatus !== "function") return;
+  ctx.ui.setStatus(STATUS_KEY, style ? `style: ${style.name}` : undefined);
+}
+
+export default function outputStyles(pi: ExtensionAPI): void {
+  pi.on("session_start", (_event, ctx) => {
+    refreshStatus(ctx, resolveActiveStyle(ctx.cwd));
+    if (started || !ctx.hasUI) return;
+    started = true;
+    startHintPoller(ctx);
+    pi.on("session_shutdown", () => {
+      started = false;
+      lastHintInput = null;
+    });
+  });
+
+  pi.on("before_agent_start", (event, ctx) => {
+    try {
+      const style = resolveActiveStyle(ctx.cwd);
+      if (!style) {
+        refreshStatus(ctx, null);
+        return;
+      }
+      // Apply first; only reflect the style in the status line once the prompt
+      // was actually augmented, so a swallowed throw never advertises a style
+      // the turn did not apply.
+      const systemPrompt = applyStyle(event.systemPrompt ?? "", style);
+      refreshStatus(ctx, style);
+      return { systemPrompt };
+    } catch {
+      return; // never fail a turn over a styling concern
+    }
+  });
+
+  pi.registerCommand("style", {
+    description:
+      "Select an output style (injected as the # Personality block of the system prompt), or clear it. Usage: /style [name|off] [--save] [--project]",
+    getArgumentCompletions: argumentPrefix => styleCompletions(argumentPrefix, process.cwd()),
+    handler: (args, ctx) => {
+      const { name, persist } = parseStyleCommandArgs(args);
+      const styles = discoverStyles(styleDirs(ctx.cwd));
+      const available = [...styles.keys()].sort().join(", ") || "(none)";
+
+      const unknownFlags = args
+        .trim()
+        .split(/\s+/)
+        .filter(t => t.startsWith("--") && !KNOWN_FLAGS.includes(t));
+      if (unknownFlags.length > 0) {
+        ctx.ui.notify(`Ignored unknown flag(s): ${unknownFlags.join(", ")}`, "warning");
+      }
+
+      if (!name) {
+        const current = resolveActiveStyle(ctx.cwd, styles);
+        const listing = [...styles.values()]
+          .sort((a, b) => a.name.localeCompare(b.name))
+          .map(s => (s.description ? `${s.name} — ${s.description}` : s.name))
+          .join("\n");
+        ctx.ui.notify(`Active style: ${current?.name ?? "(none)"}\nAvailable:\n${listing || "(none)"}`, "info");
+        return;
+      }
+      if (OFF_WORDS[name.toLowerCase()]) {
+        session = { type: "off" };
+        let offScope = "this session";
+        try {
+          if (persist === "user") {
+            writeState(userStateFile(), {});
+            offScope = "cleared · user default";
+          } else if (persist === "project") {
+            writeState(projectStateFile(ctx.cwd), {});
+            offScope = "cleared · project default";
+          }
+        } catch (err) {
+          ctx.ui.notify(`Cleared for this session, but updating the saved default failed: ${String(err)}`, "warning");
+        }
+        refreshStatus(ctx, null);
+        ctx.ui.notify(`Output style off (${offScope}).`, "info");
+        return;
+      }
+      if (!styles.has(name)) {
+        ctx.ui.notify(`Unknown style "${name}". Available: ${available}`, "error");
+        return;
+      }
+
+      session = { type: "style", name };
+      let scope = "this session";
+      try {
+        if (persist === "user") {
+          writeState(userStateFile(), { active: name });
+          scope = "saved · user default";
+        } else if (persist === "project") {
+          writeState(projectStateFile(ctx.cwd), { active: name });
+          scope = "saved · project default";
+        }
+      } catch (err) {
+        ctx.ui.notify(`Applied for this session, but saving failed: ${String(err)}`, "warning");
+      }
+      refreshStatus(ctx, styles.get(name) ?? null);
+      ctx.ui.notify(`Output style → "${name}" (${scope}).`, "info");
+    },
+  });
+}

package/extensions/styles/concise.md

@@ -0,0 +1,5 @@
+---
+name: concise
+description: Minimal words; answer first, no preamble
+---
+Answer in the fewest words that are still correct. Lead with the conclusion, then only the essential supporting detail. No preamble, no restating the question, no summary. Prefer fragments and lists over paragraphs. Omit pleasantries.

package/extensions/styles/diagrams-first.md

@@ -0,0 +1,5 @@
+---
+name: diagrams-first
+description: Lead structural/flow explanations with a Mermaid diagram
+---
+When explaining code structure, architecture, control flow, or a request path, begin with a Mermaid diagram (```mermaid fenced block) showing the structure, then explain in prose. Use `flowchart TD` for control/data flow and `sequenceDiagram` for request/response paths. Keep diagrams under ~15 nodes; split a larger system into multiple focused diagrams.

package/extensions/styles/eli5.md

@@ -0,0 +1,13 @@
+---
+name: eli5
+description: keep it simple pls
+---
+It's been a long day and my brain is fried, talk to me like I'm 5.
+
+Small words, short sentences, short paragraphs. If you have to use a big word, explain it right after. Only return what's actually necessary.
+
+Just tell me what you did, did it work, what do I do now.
+
+If I have to decide something: 2 options max, the context I need to pick fast, and which one you'd go with.
+
+Keep paths and commands exact. I have no brain cells left for the rest.

package/extensions/styles/explanatory.md

@@ -0,0 +1,5 @@
+---
+name: explanatory
+description: Complete the task, then add a short "why" insight
+---
+Complete the task normally. After each substantive change or decision, add a brief "Insight:" note (one or two sentences) explaining why this approach, what tradeoff it makes, or what codebase pattern it follows. Keep insights short and specific — they supplement the work, they do not replace it.

package/extensions/styles/reviewer.md

@@ -0,0 +1,5 @@
+---
+name: reviewer
+description: Critical code-review lens; risks, edge cases, and quality
+---
+Adopt a critical code-review lens. For any code you read or write, actively surface: correctness bugs, unhandled edge cases, security and injection risks, performance concerns, and readability/maintainability issues. Call out risky assumptions explicitly. When you propose a change, note what could break and how to verify it. Prefer specific, actionable observations over general praise.

package/extensions/styles/ste.md

@@ -0,0 +1,50 @@
+---
+name: ste
+description: Write clear prose in ASD-STE100 Simplified Technical English with action-first replies
+---
+Write clear prose in ASD-STE100 Simplified Technical English. Layer 1 governs chat replies, tasks, issues, pull request descriptions, commit messages, documentation, release notes, tool descriptions, error messages, and runbooks. Layer 2 applies only to chat replies addressed to a person, tasks, issues, pull request descriptions, and commit messages. Layer 1 does not govern code, identifiers, command syntax, log output, or fenced code blocks. Neither layer governs blogs, essays, video scripts, or marketing copy.
+
+# Layer 1 — Words
+
+Use one name for one thing. Pick one term and reuse it. Prefer short common words: start, use, help, make sure, before, after, about, get, and show. Avoid marketing adjectives. Use American spelling.
+
+Use active voice when the actor is known. Use a verb for an action. Use simple tenses. Do not stack auxiliary verbs. Do not use an -ing main verb when a simple tense works. Avoid phrasal verbs such as "spin up" and "roll out". Replace nominalizations with verbs.
+
+Write one instruction per sentence. Keep instructions to 20 words or fewer. Keep descriptive sentences to 25 words or fewer. Put a comma after a condition before its command. Use articles when they apply. Do not use contractions. Do not use semicolons. Write two sentences instead.
+
+Keep one topic in each paragraph. Limit a paragraph to six sentences. Write procedures as numbered vertical lists. Put one imperative action in each item. Put a condition before the command it protects.
+
+Use WARNING for risk of injury, CAUTION for risk of damage, and NOTE for information only. Put a warning directly before the step it protects. Start with the command or condition, then state the risk.
+
+Use two word modes:
+
+- STRICT applies every rule to procedures, runbooks, safety text, and error messages. Use "but" instead of "however", "because" instead of "since" for causes, "can" instead of "may", "must" instead of "should" or "shall", "use" or "with" instead of "using", "obey" instead of "follow", and "push" instead of "press" for physical controls.
+- STE-FLAVORED applies the sentence, paragraph, tense, active-voice, and no-phrasal-verb rules to general prose. Keep natural vocabulary.
+
+# Layer 2 — Reply shape
+Apply this layer only to chat replies addressed to a person, tasks, issues, pull request descriptions, and commit messages.
+
+Lead with the next action. Put a command, path, or useful snippet on the first line. Do not start with context, a plan, a recap, or an announcement of what you will do.
+
+Number a multi-step task. Keep each step to one bounded action. Cap an action list at five items. Split a longer list into "do now" and "later", or "must" and "nice to have".
+
+End with one action that takes less than two minutes. Name the next action if work remains. Do not add a generic offer to help.
+
+For multi-turn work, restate the current state in every turn. Give time estimates in minutes, hours, or days. Show what now works with a concrete command, path, or result.
+
+State errors matter-of-factly. Give the failing path, observed result, cause, and fix. Suppress tangents until the first issue is complete. Ask a separate question before starting a second issue.
+
+Break these Layer 2 rules when the reader asks for an explanation or walkthrough, when a destructive action needs confirmation, when three debug turns failed, or when the request is genuinely ambiguous. Keep the command-first order when it still fits. Skip the Layer 2 first-line and last-line checks when an exception applies.
+
+# Conflict rules
+
+Keep articles in sentences. Allow terse labels in lists. Apply the five-item cap to action lists, not reference tables or rule lists. Put the command first, then connect related explanation. Keep qualifiers that bound a claim. Remove empty hedges.
+
+# Self-check
+
+Before sending Layer 1 text, check the sentence and paragraph limits. Replace semicolons and contractions. Change known-actor passive voice to active voice. Replace nominalizations, stacked auxiliaries, -ing main verbs, and phrasal verbs.
+
+For Layer 2 text, check that the first line gives the next action and that the last line gives one concrete next action or ends the text. Skip this check when an exception applies.
+
+This style fixes the form of unclear writing. It cannot make an unsupported claim true.
+

package/extensions/styles/teacher.md

@@ -0,0 +1,5 @@
+---
+name: teacher
+description: Teach as you go; explain concepts before applying them
+---
+Act as a patient teacher. Before making a non-trivial change, explain the underlying concept in one or two sentences, then make the change. Prefer showing the reasoning over just the result. When you use an unfamiliar API or pattern, say what it does and why it fits. Assume the reader wants to learn, not just receive an answer.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "pi-native-output-styles",
+  "version": "0.4.0",
+  "description": "Named, swappable system-prompt styles for Pi — live /style switcher with native .pi/ directory support.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "extension",
+    "output-styles",
+    "system-prompt",
+    "persona",
+    "personality"
+  ],
+  "license": "MIT",
+  "author": "code-koan",
+  "contributors": ["LoneExile"],
+  "type": "module",
+  "homepage": "https://github.com/code-koan/pi-native-output-styles#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/code-koan/pi-native-output-styles.git" },
+  "bugs": { "url": "https://github.com/code-koan/pi-native-output-styles/issues" },
+  "pi": {
+    "extensions": ["./extensions"]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.0"
+  },
+  "files": ["extensions", "README.md", "CHANGELOG.md", "LICENSE"]
+}