feat(output-styles): customizable response formatting via /output-style

Markdown files in ~/.codebase/output-styles/<name>.md (user) or
<cwd>/.codebase/output-styles/ (project) reshape how the agent writes
its answers — terse, explanatory, report-mode, whatever. The body is
appended to the system prompt as a 'Response style' section.

/output-style lists available styles, /output-style <id> activates one
(persisted to config; the agent rebuilds in place so it takes effect
immediately while keeping the conversation), /output-style off clears.
Project styles override user styles on id clash. Mirrors Claude Code's
outputStyles.

Extracted the skills frontmatter parser into src/config/frontmatter.ts
so both subsystems share it (local-loader.ts now imports it instead of
its own copy). 12 new tests cover the loader (layering, empty-skip,
case-insensitive resolve) and config persistence.

Also drops three dead biome-ignore suppressions in cap-tool-result.

Author: halfaipg

CLAUDE.md

@@ -189,6 +189,27 @@ the system prompt:
 - `CODEX.md`
 - `.cursorrules`
 
+## Output styles
+
+Reshape how the agent writes its answers (terse / explanatory /
+report-mode / …) without touching the base prompt. Markdown files in
+`~/.codebase/output-styles/<name>.md` (user) or
+`<cwd>/.codebase/output-styles/<name>.md` (project, wins on id clash):
+
+```markdown
+---
+name: Terse
+description: One-liners, no preamble.
+---
+Answer in as few words as possible. Skip restating the question.
+```
+
+`/output-style` lists them, `/output-style <id>` activates one (the
+body is appended to the system prompt and the agent rebuilds in place),
+`/output-style off` clears it. The choice persists in
+`~/.codebase/config.json`. Same frontmatter parser as skills
+(`src/config/frontmatter.ts`).
+
 ## Direct dependencies
 
 Runtime:

src/agent/agent.ts

@@ -7,6 +7,7 @@ import { CredentialsStore } from "../auth/credentials.js";
 import { TokenManager } from "../auth/token-manager.js";
 import { CompactionEngine } from "../compaction/engine.js";
 import { CompactionMonitor } from "../compaction/monitor.js";
+import { getOutputStyle } from "../config/output-styles.js";
 import { ConfigStore } from "../config/store.js";
 import { DiagnosticsEngine, formatDiagnostics } from "../diagnostics/engine.js";
 import { GlueClient, resolveGlueModels } from "../glue/client.js";
@@ -226,7 +227,8 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 	// .cursorrules) gets pinned to the prompt so the agent sees the
 	// project's conventions on every turn. Memory addendum is appended
 	// after — it's the user's accumulated long-term notes.
-	const fullSystemPrompt = systemPrompt + buildProjectFilesAddendum(cwd) + buildMemoryAddendum(memory);
+	const fullSystemPrompt =
+		systemPrompt + buildProjectFilesAddendum(cwd) + buildMemoryAddendum(memory) + buildOutputStyleAddendum(persistedConfig, cwd);
 
 	const agent = new Agent({
 		initialState: {
@@ -471,6 +473,22 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 	};
 }
 
+/**
+ * Build the output-style addendum appended to the system prompt. When a
+ * style is selected in config and resolvable from
+ * ~/.codebase/output-styles or <cwd>/.codebase/output-styles, its body
+ * is wrapped in a labeled section so the model treats it as formatting
+ * guidance. Returns "" when no style is active or the named style is
+ * missing (e.g. config points at a deleted file).
+ */
+function buildOutputStyleAddendum(config: ConfigStore, cwd: string): string {
+	const id = config.outputStyle();
+	if (!id) return "";
+	const style = getOutputStyle(id, { cwd });
+	if (!style) return "";
+	return `\n\n# Response style: ${style.name}\n${style.body}`;
+}
+
 /** Extract the trailing assistant text content from an array of messages. */
 function lastAssistantText(messages: AgentMessage[]): string | undefined {
 	for (let i = messages.length - 1; i >= 0; i--) {

src/commands/builtins/index.ts

@@ -6,6 +6,7 @@ import { context, debug, help, pwd, whoami } from "./info.js";
 import { init } from "./init.js";
 import { memory } from "./memory.js";
 import { modelCmd, modelsCmd } from "./model.js";
+import { outputStyleCmd } from "./output-style.js";
 import { projects } from "./projects.js";
 import { commit, diff, review } from "./scm.js";
 import { clear, compact, exit, fresh, redo, resume, session } from "./session.js";
@@ -19,6 +20,7 @@ export const BUILTIN_COMMANDS: readonly Command[] = [
 	cost,
 	modelCmd,
 	modelsCmd,
+	outputStyleCmd,
 	whoami,
 	copy,
 	diff,

src/commands/builtins/output-style.ts

@@ -0,0 +1,85 @@
+import { loadOutputStyles } from "../../config/output-styles.js";
+import { ConfigStore } from "../../config/store.js";
+import type { Command } from "../types.js";
+
+/**
+ * /output-style — list, set, or clear the active response style.
+ *
+ * Styles are Markdown files in ~/.codebase/output-styles/ (or the
+ * project's .codebase/output-styles/) whose body is appended to the
+ * system prompt to reshape how the agent writes its answers.
+ *
+ * Setting a style persists it to config and rebuilds the agent so it
+ * takes effect immediately while keeping the conversation. The rebuild
+ * preserves the active model (via the persisted model preference, or
+ * the proxy default).
+ */
+export const outputStyleCmd: Command = {
+	name: "output-style",
+	aliases: ["style"],
+	description: "Show, set, or clear the response style (from ~/.codebase/output-styles/*.md).",
+	handler: async (args, ctx) => {
+		const arg = args.trim();
+		const config = new ConfigStore({ cwd: ctx.bundle.toolContext.cwd });
+		const styles = loadOutputStyles({ cwd: ctx.bundle.toolContext.cwd });
+		const active = config.outputStyle();
+
+		// No args → list available styles + which is active.
+		if (!arg) {
+			if (styles.length === 0) {
+				ctx.emit("No output styles found.");
+				ctx.emit("Create one at ~/.codebase/output-styles/<name>.md with a Markdown body, e.g.:");
+				ctx.emit("  ---");
+				ctx.emit("  name: Terse");
+				ctx.emit("  description: One-liners, no preamble.");
+				ctx.emit("  ---");
+				ctx.emit("  Answer in as few words as possible.");
+				return { handled: true };
+			}
+			ctx.emit("Output styles (* = active):");
+			for (const s of styles) {
+				const marker = s.id === active ? "*" : " ";
+				ctx.emit(`  ${marker} ${s.id}${s.description ? `  · ${s.description}` : ""}`);
+			}
+			ctx.emit(active ? `Clear with /output-style off.` : "Set with /output-style <id>.");
+			return { handled: true };
+		}
+
+		// Clear.
+		if (arg === "off" || arg === "none" || arg === "clear" || arg === "default") {
+			if (!active) {
+				ctx.emit("No output style is active.");
+				return { handled: true };
+			}
+			config.setOutputStyle(null);
+			await rebuild(ctx, config);
+			ctx.emit("Output style cleared.");
+			return { handled: true };
+		}
+
+		// Set.
+		const want = arg.toLowerCase();
+		const match = styles.find((s) => s.id === want);
+		if (!match) {
+			ctx.emit(`No output style named "${arg}".`);
+			if (styles.length > 0) ctx.emit(`Available: ${styles.map((s) => s.id).join(", ")}`);
+			return { handled: true };
+		}
+		config.setOutputStyle(match.id);
+		await rebuild(ctx, config);
+		ctx.emit(`Output style set to "${match.id}"${match.description ? ` — ${match.description}` : ""}.`);
+		return { handled: true };
+	},
+};
+
+/**
+ * Rebuild the agent so the new system prompt (with/without the style)
+ * takes effect now, preserving the conversation. Re-applies the model
+ * the user was already on: the persisted preference if any, else the
+ * proxy default (null).
+ */
+async function rebuild(ctx: Parameters<typeof outputStyleCmd.handler>[1], config: ConfigStore): Promise<void> {
+	const preferred = config.preferredModel();
+	const spec = preferred?.modelId ? { provider: preferred.provider, modelId: preferred.modelId } : null;
+	await ctx.switchModel(spec);
+}

src/config/frontmatter.ts

@@ -0,0 +1,76 @@
+/**
+ * Minimal markdown-with-frontmatter parser, shared by skills and
+ * output styles. Splits a `.md` file into its YAML-ish header and body.
+ *
+ * The accepted YAML subset is deliberately boring so users can
+ * hand-write headers without a real YAML engine: each non-blank line is
+ * `key: value`, `[a, b, c]` becomes a string list, quoted strings honor
+ * `"…"`/`'…'`. No nested objects, multi-line values, or anchors.
+ */
+
+export interface ParsedMarkdown {
+	frontmatter: Record<string, string | readonly string[]>;
+	body: string;
+}
+
+/**
+ * Split a markdown file into frontmatter + body. Tolerates files with
+ * no frontmatter (whole file becomes the body) and preserves the body's
+ * leading whitespace so prompt authors who want blank lines get them.
+ */
+export function parseMarkdownWithFrontmatter(raw: string): ParsedMarkdown {
+	const FENCE = "---";
+	const normalized = raw.replace(/^/, ""); // strip BOM
+	if (!normalized.startsWith(FENCE)) {
+		return { frontmatter: {}, body: normalized };
+	}
+	const closeIdx = normalized.indexOf(`\n${FENCE}`, FENCE.length);
+	if (closeIdx === -1) {
+		return { frontmatter: {}, body: normalized };
+	}
+	const fmText = normalized.slice(FENCE.length, closeIdx).trim();
+	const bodyStart = closeIdx + 1 + FENCE.length;
+	const body = normalized.slice(bodyStart).replace(/^\r?\n/, "");
+	return { frontmatter: parseFrontmatter(fmText), body };
+}
+
+export function parseFrontmatter(text: string): Record<string, string | readonly string[]> {
+	const out: Record<string, string | readonly string[]> = {};
+	for (const rawLine of text.split(/\r?\n/)) {
+		const line = rawLine.trim();
+		if (!line || line.startsWith("#")) continue;
+		const colon = line.indexOf(":");
+		if (colon === -1) continue;
+		const key = line.slice(0, colon).trim();
+		const value = line.slice(colon + 1).trim();
+		if (!key) continue;
+		if (value.startsWith("[") && value.endsWith("]")) {
+			out[key] = value
+				.slice(1, -1)
+				.split(",")
+				.map((s) => unquote(s.trim()))
+				.filter((s) => s.length > 0);
+		} else {
+			out[key] = unquote(value);
+		}
+	}
+	return out;
+}
+
+export function unquote(s: string): string {
+	if (s.length >= 2 && (s.startsWith('"') || s.startsWith("'"))) {
+		const q = s[0];
+		if (s.endsWith(q)) return s.slice(1, -1);
+	}
+	return s;
+}
+
+/** Coerce a frontmatter value to a string, or undefined if it's a list. */
+export function strOrUndef(value: string | readonly string[] | undefined): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+/** Coerce a frontmatter value to a string list, or undefined if it's a scalar. */
+export function strArrOrUndef(value: string | readonly string[] | undefined): readonly string[] | undefined {
+	return Array.isArray(value) ? value : undefined;
+}

src/config/output-styles.test.ts

@@ -0,0 +1,61 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getOutputStyle, loadOutputStyles } from "./output-styles.js";
+
+describe("loadOutputStyles", () => {
+	let home: string;
+	let cwd: string;
+
+	beforeEach(() => {
+		home = mkdtempSync(join(tmpdir(), "os-home-"));
+		cwd = mkdtempSync(join(tmpdir(), "os-cwd-"));
+	});
+	afterEach(() => {
+		rmSync(home, { recursive: true, force: true });
+		rmSync(cwd, { recursive: true, force: true });
+	});
+
+	function writeStyle(root: string, name: string, content: string): void {
+		const dir = join(root, ".codebase", "output-styles");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(join(dir, name), content, "utf8");
+	}
+
+	it("returns [] when no styles exist", () => {
+		expect(loadOutputStyles({ home, cwd })).toEqual([]);
+	});
+
+	it("loads a style with frontmatter name + description", () => {
+		writeStyle(home, "terse.md", "---\nname: Terse\ndescription: Short answers.\n---\nBe brief.");
+		const styles = loadOutputStyles({ home, cwd });
+		expect(styles).toHaveLength(1);
+		expect(styles[0]).toMatchObject({ id: "terse", name: "Terse", description: "Short answers.", body: "Be brief." });
+	});
+
+	it("defaults name to the id when frontmatter omits it", () => {
+		writeStyle(home, "report.md", "Write a formal report.");
+		const styles = loadOutputStyles({ home, cwd });
+		expect(styles[0]).toMatchObject({ id: "report", name: "report", body: "Write a formal report." });
+	});
+
+	it("skips empty-body styles", () => {
+		writeStyle(home, "blank.md", "---\nname: Blank\n---\n   ");
+		expect(loadOutputStyles({ home, cwd })).toEqual([]);
+	});
+
+	it("project styles override user styles with the same id", () => {
+		writeStyle(home, "voice.md", "user version");
+		writeStyle(cwd, "voice.md", "project version");
+		const styles = loadOutputStyles({ home, cwd });
+		expect(styles).toHaveLength(1);
+		expect(styles[0].body).toBe("project version");
+	});
+
+	it("getOutputStyle resolves case-insensitively", () => {
+		writeStyle(home, "Terse.md", "Be brief.");
+		expect(getOutputStyle("TERSE", { home, cwd })?.body).toBe("Be brief.");
+		expect(getOutputStyle("nope", { home, cwd })).toBeUndefined();
+	});
+});