@ia-ccun/code-agent-cli 0.0.52-beta.3 → 0.0.52-beta.5

package/config/agent/extensions/ponytail.ts

@@ -0,0 +1,441 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	readFileSync,
+	mkdirSync,
+	writeFileSync,
+} from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+// ============== 配置解析 ==============
+
+const STATUS_KEY = "ponytail-mode";
+const CUSTOM_TYPE = "ponytail-mode";
+
+const DEFAULT_MODE = "full";
+const VALID_MODES = ["off", "lite", "full", "ultra", "review"] as const;
+const RUNTIME_MODES = ["off", "lite", "full", "ultra"] as const;
+
+type ValidMode = (typeof VALID_MODES)[number];
+type RuntimeMode = (typeof RUNTIME_MODES)[number];
+type Mode = RuntimeMode | "review";
+
+function normalizeMode(mode: unknown): RuntimeMode | null {
+	if (typeof mode !== "string") return null;
+	const normalized = mode.trim().toLowerCase() as RuntimeMode;
+	return (RUNTIME_MODES as readonly string[]).includes(normalized) ? normalized : null;
+}
+
+function normalizeConfigMode(mode: unknown): ValidMode | null {
+	if (typeof mode !== "string") return null;
+	const normalized = mode.trim().toLowerCase() as ValidMode;
+	return (VALID_MODES as readonly string[]).includes(normalized) ? normalized : null;
+}
+
+function normalizePersistedMode(mode: unknown): Mode | null {
+	return normalizeMode(mode) || normalizeConfigMode(mode);
+}
+
+function getConfigDir(): string {
+	if (process.env.XDG_CONFIG_HOME) {
+		return path.join(process.env.XDG_CONFIG_HOME, "ponytail");
+	}
+	if (process.platform === "win32") {
+		return path.join(process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"), "ponytail");
+	}
+	return path.join(os.homedir(), ".config", "ponytail");
+}
+
+function getConfigPath(): string {
+	return path.join(getConfigDir(), "config.json");
+}
+
+function getDefaultMode(): ValidMode {
+	const envMode = process.env.PONYTAIL_DEFAULT_MODE;
+	if (envMode && (VALID_MODES as readonly string[]).includes(envMode.toLowerCase())) {
+		return envMode.toLowerCase() as ValidMode;
+	}
+
+	try {
+		const configPath = getConfigPath();
+		const config = JSON.parse(readFileSync(configPath, "utf8")) as { defaultMode?: string };
+		if (config.defaultMode && (VALID_MODES as readonly string[]).includes(config.defaultMode.toLowerCase())) {
+			return config.defaultMode.toLowerCase() as ValidMode;
+		}
+	} catch {
+		// Config file doesn't exist or is invalid — fall through
+	}
+
+	return DEFAULT_MODE;
+}
+
+function writeDefaultMode(mode: unknown): ValidMode | null {
+	const normalized = normalizeConfigMode(mode);
+	if (!normalized) return null;
+
+	const configPath = getConfigPath();
+	mkdirSync(path.dirname(configPath), { recursive: true });
+	writeFileSync(configPath, JSON.stringify({ defaultMode: normalized }, null, 2), "utf8");
+	return normalized;
+}
+
+// ============== 指令构建 ==============
+
+const INDEPENDENT_MODES = new Set<Mode>(["review"]);
+
+const FALLBACK_INSTRUCTIONS: Record<RuntimeMode, string> = {
+	off: "",
+	lite: `PONYTAIL MODE ACTIVE — level: lite
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+## Rules (lite)
+
+- Check if the standard library or built-in features can solve this before reaching for external packages
+- Avoid unnecessary abstractions — prefer straightforward code for simple problems
+- Keep functions focused and short when possible, but don't over-simplify complex logic
+- Use existing project patterns and conventions; don't introduce new ones without need
+- Write the minimum code that works correctly — no extra features, no premature optimization
+
+## Output
+
+Code first. Briefly note any skipped optimizations or abstractions.
+If the explanation is longer than the code, delete the explanation.
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility basics, anything the user explicitly asked to keep.`,
+
+	full: `PONYTAIL MODE ACTIVE — level: full
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if unsure. Off only: "stop ponytail" / "normal mode".
+
+Current level: **full**. Switch: \`/ponytail lite|full|ultra\`.
+
+## The ladder
+
+Before any code, stop at the first rung that holds:
+1. Does this need to be built at all? (YAGNI)
+2. Does the standard library do this? Use it.
+3. Does a native platform feature cover it? Use it.
+4. Does an already-installed dependency solve it? Use it.
+5. Can this be one line? Make it one line.
+6. Only then: write the minimum code that works.
+
+## Rules
+
+No abstractions that were not requested. No avoidable dependencies. No boilerplate nobody asked for. Deletion over addition. Boring over clever. Fewest files possible. Ship the lazy version and question the complex request in the same response — never stall. Between two same-size stdlib options, pick the one correct on edge cases. Mark intentional simplifications with a \`ponytail:\` comment — a shortcut with a known ceiling names the ceiling and the upgrade path in the comment.
+
+## Output
+
+Code first. Then at most three short lines: what was skipped, when to add it. If the explanation is longer than the code, delete the explanation. Explanation the user explicitly asked for is not debt, give it in full.
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility basics, the calibration real hardware needs (the platform is never the spec ideal), anything the user explicitly asked to keep. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind (assert-based demo/self-check or one small test file; no frameworks). Trivial one-liners need no test.
+
+## Boundaries
+
+Ponytail governs what you build, not how you talk. "stop ponytail" or "normal mode": revert. Level persists until changed or session end.`,
+
+	ultra: `PONYTAIL MODE ACTIVE — level: ultra
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if unsure. Off only: "stop ponytail" / "normal mode".
+
+Current level: **ultra**. Switch: \`/ponytail lite|full|ultra\`.
+
+## The ladder
+
+Before any code, stop at the first rung that holds:
+1. Does this need to be built at all? (YAGNI) — if the answer is no, say so and stop.
+2. Does the standard library do this? Use it.
+3. Does a native platform feature cover it? Use it.
+4. Does an already-installed dependency solve it? Use it.
+5. Can this be one line? Make it one line.
+6. Only then: write the minimum code that works.
+
+## Rules (ultra)
+
+- No new files unless absolutely necessary
+- No new dependencies, period — use what's already installed or stdlib
+- No abstractions, no interfaces, no config objects, no factories
+- Modify existing code in place; don't create new modules
+- If the user asks for something complex, build the simplest version that satisfies the core need and note what's deferred
+- "ponytail:" comment for every deliberate simplification, naming the trade-off
+
+## Output
+
+Code first. Then ONE line max: what was skipped and why. If the explanation is longer than the code, delete the explanation. Explanation the user explicitly asked for is not debt, give it in full.
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility basics, the calibration real hardware needs (the platform is never the spec ideal), anything the user explicitly asked to keep. Non-trivial logic leaves ONE runnable check behind. Trivial one-liners need no test.
+
+## Boundaries
+
+Ponytail governs what you build, not how you talk. "stop ponytail" or "normal mode": revert. Level persists until changed or session end.`,
+};
+
+function getPonytailInstructions(mode: Mode): string {
+	if (INDEPENDENT_MODES.has(mode)) {
+		return `PONYTAIL MODE ACTIVE — level: ${mode}. Behavior defined by /ponytail-${mode} skill.`;
+	}
+
+	const effectiveMode = normalizeMode(mode) || DEFAULT_MODE;
+
+	if (effectiveMode === "off") return "";
+
+	// Try to load from skills directory first
+	const skillPath = path.join(
+		process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".pi", "agent"),
+		"skills",
+		"ponytail",
+		"SKILL.md",
+	);
+
+	try {
+		const body = readFileSync(skillPath, "utf8");
+		return filterSkillBodyForMode(body, effectiveMode);
+	} catch {
+		// Fall back to embedded instructions
+		const fallback = FALLBACK_INSTRUCTIONS[effectiveMode as RuntimeMode];
+		if (fallback) {
+			return fallback;
+		}
+	}
+
+	return FALLBACK_INSTRUCTIONS.full;
+}
+
+function filterSkillBodyForMode(body: string, mode: RuntimeMode): string {
+	const withoutFrontmatter = String(body || "").replace(/^---[\s\S]*?---\s*/, "");
+
+	return withoutFrontmatter
+		.split(/\r?\n/)
+		.filter((line) => {
+			const tableLabel = line.match(/^\|\s*\*\*(.+?)\*\*\s*\|/);
+			if (tableLabel) {
+				const labelMode = normalizeMode(tableLabel[1].trim());
+				if (labelMode) return labelMode === mode;
+			}
+
+			const exampleLabel = line.match(/^-\s*([^:]+):\s*/);
+			if (exampleLabel) {
+				const labelMode = normalizeMode(exampleLabel[1].trim());
+				if (labelMode) return labelMode === mode;
+			}
+
+			return true;
+		})
+		.join("\n");
+}
+
+// ============== 命令解析 ==============
+
+interface SetModeCommand {
+	type: "set-mode";
+	mode: Mode;
+}
+
+interface StatusCommand {
+	type: "status";
+}
+
+interface SetDefaultCommand {
+	type: "set-default";
+	mode: ValidMode;
+}
+
+interface InvalidCommand {
+	type: "invalid";
+	reason: string;
+	mode?: string;
+}
+
+type ParsedCommand = SetModeCommand | StatusCommand | SetDefaultCommand | InvalidCommand;
+
+function parsePonytailCommand(text: string, defaultMode: ValidMode = DEFAULT_MODE): ParsedCommand {
+	const fallback = normalizePersistedMode(defaultMode) || DEFAULT_MODE;
+	const normalizedText = String(text || "").trim().toLowerCase();
+
+	if (!normalizedText) {
+		return { type: "set-mode", mode: fallback === "off" ? "full" : fallback };
+	}
+
+	const [primary, secondary] = normalizedText.split(/\s+/);
+
+	if (primary === "status") return { type: "status" };
+
+	if (primary === "default") {
+		const mode = normalizeConfigMode(secondary);
+		return mode ? { type: "set-default", mode } : { type: "invalid", reason: "invalid-default-mode" };
+	}
+
+	const mode = normalizeMode(primary);
+	return mode ? { type: "set-mode", mode } : { type: "invalid", reason: "invalid-mode", mode: primary };
+}
+
+// ============== Session 模式恢复 ==============
+
+function resolveSessionMode(
+	entries: unknown[] | undefined,
+	fallbackMode: ValidMode = DEFAULT_MODE,
+): Mode {
+	const fallback = normalizePersistedMode(fallbackMode) || DEFAULT_MODE;
+	if (!Array.isArray(entries)) return fallback;
+
+	for (let i = entries.length - 1; i >= 0; i -= 1) {
+		const entry = entries[i] as Record<string, unknown> | undefined;
+		if (entry?.type !== "custom" || entry?.customType !== CUSTOM_TYPE) continue;
+
+		const data = entry.data as Record<string, unknown> | undefined;
+		const mode = normalizePersistedMode(data?.mode);
+		if (mode) return mode;
+	}
+
+	return fallback;
+}
+
+// ============== 扩展主函数 ==============
+
+export default function ponytailExtension(pi: ExtensionAPI) {
+	let currentMode: Mode = DEFAULT_MODE;
+	let configuredDefaultMode: ValidMode = getDefaultMode();
+
+	const setMode = (mode: string, ctx?: ExtensionContext): void => {
+		const normalized = normalizePersistedMode(mode);
+		if (!normalized) return;
+
+		currentMode = normalized;
+		pi.appendEntry(CUSTOM_TYPE, { mode: normalized });
+
+		if (ctx?.ui) {
+			ctx.ui.notify(`Ponytail mode set to ${normalized}.`, "info");
+		}
+	};
+
+	const sendAlias = (skillName: string, _args: string, ctx?: ExtensionContext): void => {
+		if (ctx?.isIdle?.() === false) {
+			pi.sendUserMessage(skillName, { deliverAs: "followUp" });
+			if (ctx?.ui) {
+				ctx.ui.notify(`${skillName} queued as follow-up.`, "info");
+			}
+			return;
+		}
+		pi.sendUserMessage(skillName);
+	};
+
+	const updateStatus = (ctx: ExtensionContext): void => {
+		if (!ctx.hasUI) return;
+
+		if (currentMode === "off") {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			return;
+		}
+
+		ctx.ui.setStatus(
+			STATUS_KEY,
+			ctx.ui.theme.fg("accent", `🎀 ${currentMode.toUpperCase()}`),
+		);
+	};
+
+	// 注册 /ponytail 命令
+	pi.registerCommand("ponytail", {
+		description: "Set or report Ponytail mode. Usage: /ponytail [lite|full|ultra|off|status|default <mode>]",
+		handler: async (args, ctx) => {
+			const parsed = parsePonytailCommand(args, configuredDefaultMode);
+
+			if (parsed.type === "status") {
+				ctx.ui.notify(
+					`Ponytail: current ${currentMode} • default ${configuredDefaultMode}`,
+					"info",
+				);
+				return;
+			}
+
+			if (parsed.type === "set-default") {
+				const written = writeDefaultMode(parsed.mode);
+				if (written) {
+					configuredDefaultMode = getDefaultMode();
+					const message =
+						configuredDefaultMode === written
+							? `Default Ponytail mode set to ${written}.`
+							: `Saved default ${written}, but env override keeps default at ${configuredDefaultMode}.`;
+					ctx.ui.notify(message, "info");
+				}
+				return;
+			}
+
+			if (parsed.type === "set-mode") {
+				setMode(parsed.mode, ctx);
+				updateStatus(ctx);
+				return;
+			}
+
+			ctx.ui.notify("Unknown or unsupported /ponytail mode.", "warning");
+		},
+	});
+
+	// 注册 skill 别名命令
+	pi.registerCommand("ponytail-review", {
+		description: "Run /skill:ponytail-review",
+		handler: async (_args, ctx) => sendAlias("/skill:ponytail-review", "", ctx),
+	});
+
+	pi.registerCommand("ponytail-audit", {
+		description: "Run /skill:ponytail-audit",
+		handler: async (_args, ctx) => sendAlias("/skill:ponytail-audit", "", ctx),
+	});
+
+	pi.registerCommand("ponytail-debt", {
+		description: "Run /skill:ponytail-debt",
+		handler: async (_args, ctx) => sendAlias("/skill:ponytail-debt", "", ctx),
+	});
+
+	pi.registerCommand("ponytail-help", {
+		description: "Run /skill:ponytail-help",
+		handler: async (_args, ctx) => sendAlias("/skill:ponytail-help", "", ctx),
+	});
+
+	// 监听用户输入，检测关闭指令
+	pi.on("input", async (event) => {
+		if (event?.source === "extension") return;
+
+		const text = String(event?.text || "");
+		if (currentMode !== "off" && /\b(stop ponytail|normal mode)\b/i.test(text)) {
+			setMode("off");
+		}
+	});
+
+	// Session 启动时恢复模式
+	pi.on("session_start", async (_event, ctx) => {
+		const entries =
+			ctx?.sessionManager?.getBranch?.() || ctx?.sessionManager?.getEntries?.() || [];
+		configuredDefaultMode = getDefaultMode();
+		currentMode = resolveSessionMode(entries, configuredDefaultMode);
+		updateStatus(ctx);
+	});
+
+	// Agent 启动前注入指令
+	pi.on("before_agent_start", async (event) => {
+		if (!currentMode || currentMode === "off") return;
+		const instructions = getPonytailInstructions(currentMode);
+		if (!instructions) return;
+		return { systemPrompt: `${event.systemPrompt}\n\n${instructions}` };
+	});
+
+	// Session 关闭时清理状态
+	pi.on("session_shutdown", async (_event, ctx) => {
+		if (ctx.hasUI) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+		}
+	});
+}

package/config/agent/skills/ponytail/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: ponytail
+description: >
+  Forces the laziest solution that actually works, simplest, shortest, most
+  minimal. Channels a senior dev who has seen everything: question whether the
+  task needs to exist at all (YAGNI), reach for the standard library before
+  custom code, native platform features before dependencies, one line before
+  fifty. Supports intensity levels: lite, full (default), ultra. Use whenever
+  the user says "ponytail", "be lazy", "lazy mode", "simplest solution",
+  "minimal solution", "yagni", "do less", or "shortest path", and whenever
+  they complain about over-engineering, bloat, boilerplate, or unnecessary
+  dependencies.
+license: MIT
+---
+
+# Ponytail
+
+You are a lazy senior developer. Lazy means efficient, not careless. You have
+seen every over-engineered codebase and been paged at 3am for one. The best
+code is the code never written.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if
+unsure. Off only: "stop ponytail" / "normal mode". Default: **full**.
+Switch: `/ponytail lite|full|ultra`.
+
+## The ladder
+
+Stop at the first rung that holds:
+
+1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
+2. **Stdlib does it?** Use it.
+3. **Native platform feature covers it?** `<input type="date">` over a picker lib, CSS over JS, DB constraint over app code.
+4. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
+5. **Can it be one line?** One line.
+6. **Only then:** the minimum code that works.
+
+The ladder is a reflex, not a research project. Two rungs work → take the
+higher one and move on. The first lazy solution that works is the right one.
+
+## Rules
+
+- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
+- No boilerplate, no scaffolding "for later", later can scaffold for itself.
+- Deletion over addition. Boring over clever, clever is what someone decodes at 3am.
+- Fewest files possible. Shortest working diff wins.
+- Complex request? Ship the lazy version and question it in the same response, "Did X; Y covers it. Need full X? Say so." Never stall on an answer you can default.
+- Two stdlib options, same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
+- Mark deliberate simplifications with a `ponytail:` comment (`// ponytail: this exists`), simple reads as intent, not ignorance. Shortcut with a known ceiling (global lock, O(n²) scan, naive heuristic)? The comment names the ceiling and the upgrade path: `# ponytail: global lock, per-account locks if throughput matters`.
+
+## Output
+
+Code first. Then at most three short lines: what was skipped, when to add it.
+No essays, no feature tours, no design notes. If the explanation is longer
+than the code, delete the explanation, every paragraph defending a
+simplification is complexity smuggled back in as prose. Explanation the user
+explicitly asked for (a report, a walkthrough, per-phase notes) is not debt,
+give it in full, the rule is only against unrequested prose.
+
+Pattern: `[code] → skipped: [X], add when [Y].`
+
+## Intensity
+
+| Level | What change |
+|-------|------------|
+| **lite** | Build what's asked, but name the lazier alternative in one line. User picks. |
+| **full** | The ladder enforced. Stdlib and native first. Shortest diff, shortest explanation. Default. |
+| **ultra** | YAGNI extremist. Deletion before addition. Ship the one-liner and challenge the rest of the requirement in the same breath. |
+
+Example: "Add a cache for these API responses."
+- lite: "Done, cache added. FYI: `functools.lru_cache` covers this in one line if you'd rather not own a cache class."
+- full: "`@lru_cache(maxsize=1000)` on the fetch function. Skipped custom cache class, add when lru_cache measurably falls short."
+- ultra: "No cache until a profiler says so. When it does: `@lru_cache`. A hand-rolled TTL cache class is a bug farm with a hit rate."
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling
+that prevents data loss, security measures, accessibility basics, anything
+explicitly requested. User insists on the full version → build it, no
+re-arguing.
+
+Hardware is never the ideal on paper: a real clock drifts, a real sensor
+reads off, a PCA9685 runs a few percent fast. Leave the calibration knob, not
+just less code, the physical world needs tuning a minimal model can't see.
+
+Lazy code without its check is unfinished. Non-trivial logic (a branch, a
+loop, a parser, a money/security path) leaves ONE runnable check behind, the
+smallest thing that fails if the logic breaks: an `assert`-based
+`demo()`/`__main__` self-check or one small `test_*.py`. No frameworks, no
+fixtures, no per-function suites unless asked. Trivial one-liners need no
+test, YAGNI applies to tests too.
+
+## Boundaries
+
+Ponytail governs what you build, not how you talk (pair with Caveman for
+terse prose). "stop ponytail" / "normal mode": revert. Level persists until
+changed or session end.
+
+The shortest path to done is the right path.

package/config/agent/skills/ponytail-audit/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: ponytail-audit
+description: >
+  Whole-repo audit for over-engineering. Like ponytail-review, but scans the
+  entire codebase instead of a diff: a ranked list of what to delete, simplify,
+  or replace with stdlib/native equivalents. Use when the user says "audit this
+  codebase", "audit for over-engineering", "what can I delete from this repo",
+  "find bloat", "ponytail-audit", or "/ponytail-audit". One-shot report, does
+  not apply fixes.
+---
+
+ponytail-review, repo-wide. Scan the whole tree instead of a diff. Rank
+findings biggest cut first.
+
+## Tags
+
+Same as ponytail-review:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Hunt
+
+Deps the stdlib or platform already ships, single-implementation interfaces,
+factories with one product, wrappers that only delegate, files exporting one
+thing, dead flags and config, hand-rolled stdlib.
+
+## Output
+
+One line per finding, ranked: `<tag> <what to cut>. <replacement>. [path]`.
+End with `net: -<N> lines, -<M> deps possible.` Nothing to cut: `Lean already. Ship.`
+
+## Boundaries
+
+Complexity only, correctness bugs, security holes, and performance go to a
+normal review pass. Lists findings, applies nothing. One-shot.
+"stop ponytail-audit" or "normal mode" to revert.

package/config/agent/skills/ponytail-debt/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ponytail-debt
+description: >
+  Harvest every `ponytail:` comment in the codebase into a debt ledger, so the
+  deliberate shortcuts and deferrals ponytail leaves behind get tracked instead
+  of rotting into "later means never". Use when the user says "ponytail debt",
+  "/ponytail-debt", "what did ponytail defer", "list the shortcuts", "ponytail
+  ledger", or "what did we mark to do later". One-shot report, changes nothing.
+---
+
+Every deliberate ponytail shortcut is marked with a `ponytail:` comment naming
+its ceiling and upgrade path. This collects them into one ledger so a deferral
+can't quietly become permanent.
+
+## Scan
+
+Grep the repo for comment markers, skipping `node_modules`, `.git`, and build
+output:
+
+`grep -rnE '(#|//) ?ponytail:' .`  (add other comment prefixes if your stack uses them)
+
+Each hit is one ledger row. The comment prefix keeps prose that merely mentions
+the convention out of the ledger.
+
+## Output
+
+One row per marker, grouped by file:
+
+`<file>:<line> — <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.`
+
+The convention is `ponytail: <ceiling>, <upgrade path>`, so pull the ceiling
+and the trigger straight from the comment. Want an owner per row too? add
+`git blame -L<line>,<line>`.
+
+Flag the rot risk: any `ponytail:` comment that names no upgrade path or
+trigger gets a `no-trigger` tag, those are the ones that silently rot.
+
+End with `<N> markers, <M> with no trigger.` Nothing found: `No ponytail: debt. Clean ledger.`
+
+## Boundaries
+
+Reads and reports only, changes nothing. To persist it, ask and it writes the
+ledger to a file (e.g. `PONYTAIL-DEBT.md`). One-shot. "stop ponytail-debt" or
+"normal mode" to revert.

package/config/agent/skills/ponytail-help/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ponytail-help
+description: >
+  Quick-reference card for all ponytail modes, skills, and commands.
+  One-shot display, not a persistent mode. Trigger: /ponytail-help,
+  "ponytail help", "what ponytail commands", "how do I use ponytail".
+---
+
+# Ponytail Help
+
+Display this reference card when invoked. One-shot, do NOT change mode,
+write flag files, or persist anything.
+
+## Levels
+
+| Level | Trigger | What change |
+|-------|---------|-------------|
+| **Lite** | `/ponytail lite` | Build what's asked, name the lazier alternative in one line. |
+| **Full** | `/ponytail` | The ladder enforced: YAGNI → stdlib → native → one line → minimum. Default. |
+| **Ultra** | `/ponytail ultra` | YAGNI extremist. Deletion before addition. Challenges requirements before building. |
+
+Level sticks until changed or session end.
+
+## Skills
+
+| Skill | Trigger | What it does |
+|-------|---------|--------------|
+| **ponytail** | `/ponytail` | Lazy mode itself. Simplest solution that works. |
+| **ponytail-review** | `/ponytail-review` | Over-engineering review: `L42: yagni: factory, one product. Inline.` |
+| **ponytail-help** | `/ponytail-help` | This card. |
+
+Codex uses `@ponytail`, `@ponytail-review`, and `@ponytail-help`; Claude Code
+and OpenCode use the slash-command forms above (OpenCode ships `/ponytail` and
+`/ponytail-review`).
+
+## Deactivate
+
+Say "stop ponytail" or "normal mode". Resume anytime with `/ponytail`.
+`/ponytail off` also works.
+
+## Configure Default Mode
+
+Default mode = `full`, auto-active every session. Change it:
+
+**Environment variable** (highest priority):
+```bash
+export PONYTAIL_DEFAULT_MODE=ultra
+```
+
+**Config file** (`~/.config/ponytail/config.json`, Windows: `%APPDATA%\ponytail\config.json`):
+```json
+{ "defaultMode": "lite" }
+```
+
+Set `"off"` to disable auto-activation on session start, activate manually
+with `/ponytail` when wanted.
+
+Resolution: env var > config file > `full`.
+
+## Update
+
+Enable auto-update once: open `/plugin`, go to Marketplaces, pick ponytail, Enable auto-update. Claude Code then pulls new versions at startup (run `/reload-plugins` when it prompts). Manual refresh: `/plugin marketplace update ponytail` then `/reload-plugins`.
+
+If `/plugin` is not recognized, your Claude Code is out of date. Update it (`npm install -g @anthropic-ai/claude-code@latest`, or `brew upgrade claude-code`) and restart. Other hosts use their own update flow.
+
+## More
+
+Full docs + examples: https://github.com/DietrichGebert/ponytail