pi-native-output-styles 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.5.0
+
+One command, plus a bundled style and an agent that maintains styles.
+
+### Added
+
+- `/output-style <request>` hands the task to an agent that reviews, rewrites, or creates styles. The brief is short Markdown in `extensions/prompts/output-style-leader.md`, and the agent decides for itself whether to fan work out to other agents.
+- Bundled `caveman` style, from [carlosduplar/caveman-output-style-claude-code](https://github.com/carlosduplar/caveman-output-style-claude-code) (MIT, © 2026 Carlos Mello).
+
+### Changed
+
+- **`/style` is gone; `/output-style` is the only command.** A single word that names a style, `off`, or `none` is style management; anything else is a request for the agent. `/output-style` with no arguments lists what exists.
+- Style names are matched case-insensitively and resolved to their declared name.
+
 ## 0.4.0
 
 Repackaged as `pi-native-output-styles` — a Pi-only output-style switcher built on Pi's native `.pi/` directories.

package/LICENSE

@@ -2,6 +2,8 @@ MIT License
 
 Copyright (c) 2026 LoneExile
 Copyright (c) 2026 code-koan contributors
+The bundled `caveman` output style is Copyright (c) 2026 Carlos Mello
+(https://github.com/carlosduplar/caveman-output-style-claude-code), MIT.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -4,7 +4,7 @@
 [![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**.
+Named, swappable system-prompt styles for [Pi](https://pi.dev), plus an agent that can review, rewrite, and create them for you. 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/`.
 
@@ -19,17 +19,31 @@ pi install git:github.com/code-koan/pi-native-output-styles
 
 Then start a **new** session. Extensions do not hot-reload.
 
-## Use
+## One command
 
-- `/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.
+`/output-style` does both jobs. What you type decides which one you get.
 
-The style is applied every turn, and the status line shows `style: eli5`.
+**Switch styles** — the first word is a style name, `off`, or nothing:
+
+```text
+/output-style                          list styles and show the active one
+/output-style caveman                  use caveman for this session
+/output-style concise --save           and make it your default
+/output-style concise --project        save it as this project's default
+/output-style off                      clear it; --save / --project also clears the default
+```
+
+**Ask the agent to work on a style** — anything else:
+
+```text
+/output-style review the reviewer style
+/output-style 重写这个 output style，让它更简洁、更适合编程
+/output-style 创建一个适合代码 Review 的 output style
+```
+
+The rule is one line: *a single word that names a style, `off`, or `none` is management; anything else is a request for the agent.* So `/output-style concise` activates, and `/output-style rewrite concise` asks. To review a style whose name you would otherwise activate, say more than its name.
+
+While composing the command, a hint line under the editor shows both forms.
 
 ## How a style is applied
 
@@ -37,9 +51,23 @@ Pi's assembled system prompt is flat prose plus XML blocks — there is no perso
 
 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.
 
+## The style agent
+
+`/output-style <request>` hands the task to the agent with a short brief and the live picture: which style is active, both writable directories, and every style that exists with its tier and file path.
+
+The agent owns the task end to end. It decides for itself whether the work needs other agents — a review is the usual case, where prompt quality, responsibility boundaries, and conflicts/redundancy are worth splitting across children. It uses whatever delegation tool the session has, and does the analysis itself when there is none. The final write and the summary stay with it.
+
+Review findings are specific: conflicting instructions, duplicate or unenforceable rules, vague wording, over-constraining the model, content that belongs to a different concern, AI-slop voice, and rules that are hard to follow while actually working. Rewrites keep what works, delete what does not, and add only what is missing.
+
+A review reports; it does not edit. The file is written only when the request asks for a change. In observed runs the agent delegated on its own when a task had several independent angles to check, and worked solo on a small single-file review.
+
+The brief lives in [`extensions/prompts/output-style-leader.md`](extensions/prompts/output-style-leader.md) and is plain Markdown — edit it without touching code.
+
 ## Bundled styles
 
-`concise` · `explanatory` · `teacher` · `reviewer` · `diagrams-first` · `ste` · `eli5`
+`caveman` · `concise` · `explanatory` · `teacher` · `reviewer` · `diagrams-first` · `ste` · `eli5`
+
+`caveman` is [Carlos Mello's Caveman output style](https://github.com/carlosduplar/caveman-output-style-claude-code) — terse replies, no filler, same technical signal. The same repo also ships a more aggressive `caveman-ultra`; it is not bundled, but you can drop it into your own `output-styles/` directory unchanged.
 
 `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).
 
@@ -60,12 +88,12 @@ description: Teach as you go
 Act as a patient teacher. Explain the concept before applying it.
 ```
 
-The body becomes the `# Personality` block.
+`name` is lowercase kebab-case, `description` is one line and shows up in `/output-style`.
 
 Precedence:
 
 - **Definitions** (low → high): bundled < user < project.
-- **Which style is active**: session `/style` > user default > project default.
+- **Which style is active**: session `/output-style` > user default > project default.
 
 ## Config
 
@@ -91,4 +119,4 @@ 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.
+Started as a fork of [LoneExile/pi-output-styles](https://github.com/LoneExile/pi-output-styles). Bundles [caveman](https://github.com/carlosduplar/caveman-output-style-claude-code) by Carlos Mello. MIT licensed; original work © 2026 LoneExile, caveman style © 2026 Carlos Mello.

package/extensions/output-styles.ts

@@ -11,6 +11,21 @@ export interface Style {
   name: string;
   description: string;
   body: string;
+  /** Absolute file path; set by discoverStyles. */
+  path?: string;
+}
+
+/** Where a style definition was found. Only `project` and `user` are writable. */
+export type StyleTier = "bundled" | "user" | "project";
+
+export interface StyleSource {
+  dir: string;
+  tier: StyleTier;
+}
+
+export interface StyleEntry extends Style {
+  tier: StyleTier;
+  path: string;
 }
 
 type NotifyType = "info" | "warning" | "error";
@@ -25,6 +40,7 @@ interface ExtensionUI {
 interface ExtensionContext {
   cwd: string;
   hasUI: boolean;
+  isIdle?(): boolean;
   ui: ExtensionUI;
   setInterval?(callback: () => void, ms?: number): unknown;
 }
@@ -59,6 +75,7 @@ interface ExtensionAPI {
       handler: (args: string, ctx: ExtensionContext) => void | Promise<void>;
     },
   ): void;
+  sendUserMessage(content: string, options?: { deliverAs?: "steer" | "followUp" }): void;
 }
 
 export function parseStyle(text: string, fallbackName: string): Style {
@@ -99,7 +116,7 @@ export function discoverStyles(dirsLowToHigh: string[]): Map<string, Style> {
       }
       const style = parseStyle(text, entry.slice(0, -3));
       if (style.body.length === 0) continue;
-      styles.set(style.name, style);
+      styles.set(style.name, { ...style, path: join(dir, entry) });
     }
   }
   return styles;
@@ -207,20 +224,46 @@ export function parseStyleCommandArgs(args: string): StyleCommandArgs {
   return { name, persist };
 }
 
+// One command serves both jobs, so the split has to be guessable from the
+// words alone. Rule: the request is style management only when it is empty,
+// or its single non-flag word is `off`/`none` or a style that exists. Anything
+// else is a task for the agent. `/output-style concise` activates; `/output-style
+// rewrite concise` asks the agent.
+export type StyleCommandRoute = { kind: "manage" } | { kind: "task"; request: string };
+
+export function routeStyleCommand(args: string, styleNames: Iterable<string>): StyleCommandRoute {
+  const request = args.trim();
+  if (request.length === 0) return { kind: "manage" };
+  const words = request.split(/\s+/).filter(t => t.length > 0 && !t.startsWith("--"));
+  if (words.length === 0) return { kind: "manage" }; // flags only
+  if (words.length > 1) return { kind: "task", request };
+  const word = words[0].toLowerCase();
+  if (OFF_WORDS[word]) return { kind: "manage" };
+  const known = new Set([...styleNames].map(n => n.toLowerCase()));
+  return known.has(word) ? { kind: "manage" } : { kind: "task", request };
+}
+
+// Routing matches names case-insensitively, but the style map is keyed by the
+// exact declared name, so the selected name has to be canonicalised before use.
+export function resolveStyleName(name: string, styleNames: Iterable<string>): string | null {
+  const all = [...styleNames];
+  return all.find(n => n === name) ?? all.find(n => n.toLowerCase() === name.toLowerCase()) ?? null;
+}
+
 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.
+// Persistent ghost hint shown below the editor while `/output-style` 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)",
+  "/output-style <name|off> [--save] [--project]",
+  "/output-style <ask the agent to review, rewrite, or create a style>",
 ];
 
-// Pure matcher for the widget: show the hint while the input starts with a
-// `/style` command word (line start, with optional leading whitespace).
+// Pure matcher for the widget: show the hint while the input starts with the
+// `/output-style` command word (line start, optional leading whitespace).
 export function styleHintFor(text: string): string[] | null {
-  return /^\s*\/style(?:\s|$)/.test(text) ? STYLE_HINT_LINES : null;
+  return /^\s*\/output-style(?:\s|$)/.test(text) ? STYLE_HINT_LINES : null;
 }
 
 // Poller state: one started flag guards re-registration across in-process
@@ -259,9 +302,29 @@ export function startHintPoller(ctx: ExtensionContext): void {
 type SessionSelection = { type: "inherit" } | { type: "off" } | { type: "style"; name: string };
 let session: SessionSelection = { type: "inherit" };
 
-function styleDirs(cwd: string): string[] {
+export function styleSources(cwd: string): StyleSource[] {
   // low → high precedence: bundled < user < project
-  return [bundledStylesDir(), userStylesDir(), projectStylesDir(cwd)];
+  return [
+    { dir: bundledStylesDir(), tier: "bundled" },
+    { dir: userStylesDir(), tier: "user" },
+    { dir: projectStylesDir(cwd), tier: "project" },
+  ];
+}
+
+// One row per style name: the winning definition plus the file that actually
+// produced it, so a rewrite knows whether it may edit in place.
+export function styleCatalog(cwd: string): StyleEntry[] {
+  const byName = new Map<string, StyleEntry>();
+  for (const { dir, tier } of styleSources(cwd)) {
+    for (const style of discoverStyles([dir]).values()) {
+      if (style.path) byName.set(style.name, { ...style, tier, path: style.path });
+    }
+  }
+  return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function styleDirs(cwd: string): string[] {
+  return styleSources(cwd).map(s => s.dir);
 }
 
 // Argument completions for `/style <name>`: matches style names by prefix.
@@ -302,6 +365,37 @@ function refreshStatus(ctx: ExtensionContext, style: Style | null): void {
   ctx.ui.setStatus(STATUS_KEY, style ? `style: ${style.name}` : undefined);
 }
 
+// The Leader brief is plain Markdown next to the extension, so its wording can
+// be edited without touching code.
+export function leaderBrief(): string {
+  return readFileSync(join(dirname(fileURLToPath(import.meta.url)), "prompts", "output-style-leader.md"), "utf8").trim();
+}
+
+// The brief stays fixed and short. What changes per run is the live picture:
+// which style is active, where styles may be written, and what already exists.
+// The user's words are passed through untouched — this is a router, not a form.
+export function buildStyleTask(brief: string, cwd: string, active: Style | null, request: string): string {
+  const catalog = styleCatalog(cwd);
+  return [
+    brief,
+    "",
+    "## Context",
+    "",
+    `Active style: ${active?.name ?? "(none)"}`,
+    `Project style dir: ${projectStylesDir(cwd)}`,
+    `User style dir: ${userStylesDir()}`,
+    "",
+    "Available styles:",
+    ...(catalog.length
+      ? catalog.map(s => `- ${s.name} [${s.tier}] ${s.path}${s.description ? ` — ${s.description}` : ""}`)
+      : ["(none)"]),
+    "",
+    "## Request",
+    "",
+    request,
+  ].join("\n");
+}
+
 export default function outputStyles(pi: ExtensionAPI): void {
   pi.on("session_start", (_event, ctx) => {
     refreshStatus(ctx, resolveActiveStyle(ctx.cwd));
@@ -332,13 +426,30 @@ export default function outputStyles(pi: ExtensionAPI): void {
     }
   });
 
-  pi.registerCommand("style", {
+  pi.registerCommand("output-style", {
     description:
-      "Select an output style (injected as the # Personality block of the system prompt), or clear it. Usage: /style [name|off] [--save] [--project]",
+      "Select an output style, or ask the agent to review, rewrite, or create one. Usage: /output-style <name|off|what you want> [--save] [--project]",
     getArgumentCompletions: argumentPrefix => styleCompletions(argumentPrefix, process.cwd()),
     handler: (args, ctx) => {
-      const { name, persist } = parseStyleCommandArgs(args);
       const styles = discoverStyles(styleDirs(ctx.cwd));
+      const route = routeStyleCommand(args, styles.keys());
+
+      if (route.kind === "task") {
+        let task: string;
+        try {
+          task = buildStyleTask(leaderBrief(), ctx.cwd, resolveActiveStyle(ctx.cwd, styles), route.request);
+        } catch (err) {
+          ctx.ui.notify(`Could not build the output-style task: ${String(err)}`, "error");
+          return;
+        }
+        // Mid-stream the delivery mode is required; otherwise the message goes
+        // out immediately and triggers the turn.
+        pi.sendUserMessage(task, ctx.isIdle?.() === false ? { deliverAs: "followUp" } : undefined);
+        return;
+      }
+
+      const { name: requested, persist } = parseStyleCommandArgs(args);
+      const name = requested === null ? null : (resolveStyleName(requested, styles.keys()) ?? requested);
       const available = [...styles.keys()].sort().join(", ") || "(none)";
 
       const unknownFlags = args
@@ -355,7 +466,11 @@ export default function outputStyles(pi: ExtensionAPI): void {
           .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");
+        ctx.ui.notify(
+          `Active style: ${current?.name ?? "(none)"}\nAvailable:\n${listing || "(none)"}\n\n` +
+            "/output-style <name|off> [--save] [--project] to switch, or /output-style <request> to have the agent review, rewrite, or create a style.",
+          "info",
+        );
         return;
       }
       if (OFF_WORDS[name.toLowerCase()]) {

package/extensions/prompts/output-style-leader.md

@@ -0,0 +1,71 @@
+# Output style task
+
+You own this end to end: read the request, decide what work it needs, do it,
+then verify what you produced. Finish with a short report of what changed and
+where.
+
+## What an output style is
+
+A style defines **how** you behave: voice, structure, level of detail,
+interaction style. It is not a home for project architecture, coding rules,
+domain knowledge, tooling conventions, or repo facts. Anything like that is a
+responsibility-boundary bug: drop it, or say where it belongs instead.
+
+## Delegation
+
+Decide for yourself whether the task needs other agents. Delegate only when
+independent angles genuinely improve the result. A review is the usual case:
+prompt quality, responsibility boundaries, and conflicts/redundancy are worth
+splitting. Use the `subagent` tool when it is available, and run the children
+in one workflow call. If it is not available, do the analysis yourself.
+Children report findings back to you and never write files. You do the final
+write and the final summary — never hand the file off.
+
+## Reviewing
+
+Review means report, not edit. Do not change the file unless the request also
+asks for the change; offer the fix instead.
+
+Name each finding specifically: what is wrong, what it costs, and the fix.
+Look for:
+
+- instructions that conflict with each other
+- duplicate, dead, or unenforceable rules
+- vague wording that cannot be acted on
+- over-constraining the model
+- content that belongs to another concern
+- AI-slop voice: inflated claims, filler, ceremony
+- rules that are hard to follow while actually working
+
+No praise padding, and do not restate the style back at the user.
+
+## Rewriting
+
+Keep what works, delete what does not, add only what is missing. Fewer sharp
+rules beat more rules. Do not add text to look thorough, and do not quietly
+widen the scope.
+
+## Creating
+
+Write the smallest style that achieves the goal. `name` is lowercase
+kebab-case; `description` is one line and shows up in `/style`.
+
+## File format
+
+    ---
+    name: <kebab-case>
+    description: <one line>
+    ---
+    <style body>
+
+## Where to write
+
+Default to the project directory. Write to the user directory only when asked
+for personal or global. Never edit a style under a package install path — those
+are read-only bundled styles; copy one out instead.
+
+## Before you finish
+
+- Re-read what you wrote: frontmatter plus body, nothing else.
+- Confirm the file parses and the `name` matches what `/style <name>` expects.
+- State the path you wrote and what changed.

package/extensions/styles/caveman.md

@@ -0,0 +1,11 @@
+---
+name: caveman
+description: Ultra-compact replies. Less fluff. Same technical signal.
+---
+
+Smart caveman style: terse responses, keep technical substance, drop ALL fluff.
+Lead with answer. Drop articles, filler, pleasantries, hedging, preamble, recap.
+Fragments OK. Pattern: `[thing] [action] [reason]. [next step].`
+Keep technical terms, code, commands, paths, JSON, errors unchanged.
+Bullets/tables only when scan > prose.
+Normal language for safety, irreversible actions, or confusion risk.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-native-output-styles",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Named, swappable system-prompt styles for Pi — live /style switcher with native .pi/ directory support.",
   "keywords": [
     "pi-package",