4 +**Status:** Draft for review
5 +**Objective:** Create an idiomatic Pi extension named `lazy` with the same or better functionality as `DietrichGebert/ponytail`.
9 +Researched repository: `https://github.com/DietrichGebert/ponytail`.
10 +Local snapshot: `tmp/research/ponytail`.
11 +Commit: `40e50d9e03242aa5dd53ac771950f9127362b25f` on `main`.
12 +Package version observed: `4.8.4`.
14 +Primary source files inspected:
16 +- `README.md` for install UX, modes, commands, benchmark claims, and safety boundary.
17 +- `package.json` for Pi package manifest: `pi.extensions = ["./pi-extension/index.js"]`, `pi.skills = ["./skills"]`.
18 +- `pi-extension/index.js` for Pi adapter behavior.
19 +- `pi-extension/test/*.test.js` for Pi command, state, config, and prompt injection expectations.
20 +- `hooks/ponytail-config.js`, `hooks/ponytail-instructions.js`, `hooks/ponytail-runtime.js`, `hooks/ponytail-activate.js`, `hooks/ponytail-mode-tracker.js`, `hooks/ponytail-subagent.js` for shared mode/config/instruction behavior.
21 +- `skills/ponytail*/SKILL.md` for the six portable skills.
22 +- `docs/platform-native.md` for stdlib/native replacement reference content.
23 +- `docs/agent-portability.md` for host adapter model.
24 +- `benchmarks/results/2026-06-18-agentic.md` for the current benchmark claim and limitations.
25 +- `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `.opencode/plugins/ponytail.mjs`, `plugin.yaml`, `__init__.py`, `gemini-extension.json` for non-Pi adapter parity.
29 +- `/opt/pi-coding-agent/docs/extensions.md`
30 +- `/opt/pi-coding-agent/docs/packages.md`
31 +- `/opt/pi-coding-agent/docs/skills.md`
32 +- local extension patterns in `extensions/terse`, `extensions/notes`, and repo test harness patterns.
36 +Ponytail already ships a Pi adapter, but it is a thin compatibility layer inside a multi-host package.
37 +It reuses CommonJS hook files, has minimal Pi-native UI, and delegates most commands to skill prompts.
38 +`lazy` is a new Pi-only extension for this repo, so it should keep the useful behavior and drop all host portability, migration, legacy config, and compatibility shims.
42 +- Provide always-on lazy-senior-dev guidance for Pi coding sessions.
43 +- Preserve Ponytail's core ladder: YAGNI, reuse codebase, stdlib, native platform, installed dependency, one-line solution, then minimum custom code.
44 +- Preserve intensity levels: `lite`, `full`, `ultra`, and `off`.
45 +- Preserve behavior while renaming the command surface to `/lazy`, `/lazy-review`, `/lazy-audit`, `/lazy-debt`, `/lazy-gain`, `/lazy-help`.
46 +- Preserve session-local mode persistence across branch reloads using Pi session entries.
47 +- Use only Pi settings for default mode.
48 +- Preserve skill discoverability through normal Pi skills.
49 +- Add Pi-native UX that current Ponytail lacks: proper settings integration, compact status rendering, command completions, and optional direct command implementations where they beat prompt aliases.
50 +- Keep extension behavior cross-platform and shell-free by default.
51 +- Keep output injection compact and deterministic.
55 +- Reimplement all non-Pi host adapters.
56 +- Support Ponytail install/config migration.
57 +- Keep Ponytail command or skill names for compatibility.
58 +- Copy Ponytail's benchmarks or benchmark runner into this repo.
59 +- Add a new model provider, MCP server, or external service.
60 +- Automatically mutate user code when running review/audit/debt commands.
61 +- Replace Pi's built-in skills system.
62 +- Add dependencies for parsing markdown or config unless a stdlib/Node API cannot cover it.
68 +`/lazy [mode]` controls a session mode.
71 +- `lite`: build what was asked, but mention the lazier alternative briefly.
72 +- `full`: default ladder enforcement.
73 +- `ultra`: deletion-first, YAGNI-extreme, challenge nonessential requirements while still shipping the smallest safe version.
74 +- `off`: no prompt injection and no active status badge.
76 +Bare `/lazy` enables the configured default mode.
77 +If configured default is `off`, bare `/lazy` enables `full`.
78 +`/lazy status` reports session mode and default mode.
79 +`/lazy default <mode>` writes the default mode to extension settings if Pi exposes a safe setting writer; otherwise it explains the exact settings JSON entry.
83 +A user message equal to `stop lazy` or `normal mode`, ignoring case and trailing punctuation, turns the mode off.
84 +Incidental mentions such as `add a normal mode toggle` must not turn it off.
88 +On `before_agent_start`, the extension injects one lazy-mode instruction block only when mode is not `off`.
89 +The block must be built from a single canonical source inside this package, not copy-pasted across command handlers.
93 +- `LAZY MODE ACTIVE — level: <mode>` header.
95 +- Root-cause bug-fix rule: inspect callers and fix the shared route when possible.
96 +- Safety floor: never remove trust-boundary validation, data-loss handling, security, accessibility, hardware calibration, or explicitly requested behavior.
97 +- Test floor: non-trivial logic leaves one small runnable check; trivial one-liners need no test.
98 +- Output discipline: code first; short skipped/when-to-add note; no unrequested essays.
99 +- Mode-specific section only for the active mode.
101 +The injection must be idempotent per turn: repeated `before_agent_start` hooks cannot duplicate the block.
105 +In TUI/RPC UI-capable sessions, show a compact status segment:
107 +- inactive turn: `○ lazy: <mode>`
108 +- active generation: `● lazy: <mode>`
109 +- off: clear the segment
111 +Use `ctx.ui.setStatus("lazy", ...)`.
112 +Do not require theme APIs to exist; degrade silently in non-UI modes.
116 +`/lazy-review` reviews the current diff for over-engineering only.
117 +It returns one finding per line with tags: `delete`, `stdlib`, `native`, `yagni`, `shrink`.
118 +It ends with `net: -<N> lines possible.` or `Lean already. Ship.`
119 +It does not apply fixes.
121 +`/lazy-audit` scans the repository, not just the diff, for over-engineering.
122 +It ranks largest reductions first and ends with `net: -<N> lines, -<M> deps possible.` or `Lean already. Ship.`
123 +It does not apply fixes.
125 +`/lazy-debt` finds deliberate shortcut comments matching comment markers such as `// lazy:` and `# lazy:`.
126 +It reports file, line, ceiling, and upgrade trigger.
127 +It flags markers without a trigger as `no-trigger`.
128 +It changes nothing unless a future explicit `--write` option is added.
130 +When an agent turn adds a new `lazy:` marker, the extension sends a UI notification with the file count and suggests `/lazy-debt`.
131 +Detection happens after the agent turn by scanning the current git diff for newly added `lazy:` lines.
132 +No background watcher is needed.
134 +`/lazy-gain` prints a compact benchmark card.
135 +It must be honest that numbers are published benchmark medians, not current-repo savings.
136 +Prefer the current agentic figures from `2026-06-18-agentic.md`: feature tasks `LOC -54%`, `tokens -22%`, `cost -20%`, `time -27%`, `safe 100%`; safety tasks note `safe 100%` and that bare one-liner prompt slipped to `95%`.
137 +Avoid the older single-shot `80–94%` headline except as historical context.
139 +`/lazy-help` prints command, mode, deactivation, and config reference.
143 +Ship Pi skills in `extensions/lazy/skills/*/SKILL.md` exported by root `package.json`.
153 +The extension commands may either:
155 +1. directly implement deterministic behavior, or
156 +2. send `/skill:<name>` as a follow-up.
160 +- Direct extension implementation: `/lazy`, `/lazy-debt`, `/lazy-gain`, `/lazy-help`.
161 +- Skill handoff: `/lazy-review`, `/lazy-audit` because the agent must reason over code and diffs.
163 +This is better than upstream Pi adapter because deterministic commands avoid spending model turns for static cards and grep-like ledgers.
167 +Create a new extension package: `extensions/lazy`.
178 +│ ├── instructions.ts
185 +│ ├── lazy-review/SKILL.md
186 +│ ├── lazy-audit/SKILL.md
187 +│ ├── lazy-debt/SKILL.md
188 +│ ├── lazy-gain/SKILL.md
189 +│ └── lazy-help/SKILL.md
192 + ├── instructions.test.ts
194 + └── harness.test.ts
199 +Use Pi custom session entries for branch-aware mode state.
200 +Entry type: `lazy-mode`.
201 +Entry data: `{ mode: "lite" | "full" | "ultra" | "off", at: number }`.
202 +On `session_start`, replay the current branch and use the latest valid mode.
203 +If no session entry exists, use configured default.
205 +This is idiomatic Pi and better than host-level flag files because it respects session branches.
209 +Prefer Pi settings over a separate config file.
215 + "defaultMode":
"full",
221 +No legacy config compatibility.
222 +No `PONYTAIL_DEFAULT_MODE`.
223 +No `~/.config/ponytail/config.json`.
224 +Only `lazy.defaultMode` in Pi settings.
226 +Valid default modes: `off`, `lite`, `full`, `ultra`.
227 +Reject `review` as a persistent Pi mode unless a future design adds explicit review-mode semantics.
229 +Pi has `/lazy-review` for that.
231 +###
Instruction builder 233 +Keep a typed instruction builder in `src/instructions.ts`.
234 +Inputs: active mode, optional skill body text.
235 +Outputs: complete prompt block.
237 +Filtering requirement:
239 +- Remove skill frontmatter.
240 +- Keep only the active mode row in the intensity table.
241 +- Keep only the active mode example bullets.
242 +- Do not accidentally remove normal rule bullets containing colons.
244 +This keeps the useful filtering behavior without upstream compatibility code.
246 +###
Direct debt scanner 248 +Implement with Node APIs, not shell `grep`.
249 +Scan text files under `ctx.cwd`.
250 +Skip `.git`, `node_modules`, build outputs, lock/cache dirs, and large/binary files.
251 +Match common comment forms:
258 +Return bounded output and count totals.
259 +If a full list is too large, truncate and tell the user how many were omitted.
261 +###
Review and audit handoff 263 +For `/lazy-review` and `/lazy-audit`, use `pi.sendUserMessage` with `/skill:lazy-review` or `/skill:lazy-audit`.
264 +If the agent is streaming, queue as `followUp`.
265 +If idle, send immediately.
266 +Forward command args as user arguments so `/lazy-review path/to/file` works.
267 +Add argument completions for `/lazy` modes: `lite`, `full`, `ultra`, `off`, `status`, and `default`.
271 +No subagent handoff in v1.
272 +Lazy injects only into normal Pi agent turns that load the extension.
273 +It does not try to force lazy mode into SDK-created subagents.
274 +It does not export APIs for other extensions, and other extensions must not import lazy files or call lazy functions.
275 +If Pi later adds a first-class subagent prompt hook, add subagent support then.
277 +##
Package integration 279 +Root `package.json` must export the extension and skills.
280 +Add `extensions/lazy/skills` to root `pi.skills`.
281 +Current root manifest exports `extensions/*/index.ts` and selected skill dirs only, so add `extensions/lazy/skills` explicitly.
283 +Extension package `package.json` should include only peer dependencies for Pi packages if imported directly.
284 +No runtime dependency is expected.
288 +Lazy must add near-zero overhead to normal turns.
290 +- Do no repository-wide scan on startup or every prompt.
291 +- Prompt injection is string assembly only.
292 +- Status updates are constant-time.
293 +- `agent_end` marker detection reads only `git diff --numstat` and `git diff --unified=0`, and only when inside a Git worktree.
294 +- Diff scanning caps output read size and stops after the first notification-worthy marker batch.
295 +- `/lazy-debt` is the only repo-wide marker scan, runs only on explicit command, skips ignored/heavy dirs, and has file-size/output limits.
296 +- No file watchers, polling loops, timers, background daemons, or startup indexing.
297 +- No spawned shell for routine behavior except bounded `git diff` for post-turn marker detection.
298 +- If Git is unavailable or the worktree is huge, skip notification and stay silent.
302 +- `before_agent_start` instruction injection is pure and deterministic.
303 +- `agent_end` with no Git repo does no scan and returns fast.
304 +- `agent_end` scans only diff output, not the filesystem.
305 +- `/lazy-debt` respects skip dirs, file-size caps, and output caps.
309 +Use `mise run test -- lazy` or exact vitest filters once implemented.
310 +Do not bypass `mise` for repo tasks.
312 +Required unit tests:
314 +- mode normalization accepts only `off`, `lite`, `full`, `ultra`.
315 +- bare `/lazy` falls back from default `off` to `full`.
316 +- `status` and `default <mode>` parse correctly.
317 +- Pi setting default is used when no session entry exists.
318 +- session replay picks latest branch entry.
319 +- deactivation matches only standalone `stop lazy` and `normal mode`.
320 +- instruction injection includes active header and excludes inactive mode examples.
321 +- instruction filtering keeps non-mode bullets containing colons.
322 +- instruction injection is idempotent.
323 +- debt scanner finds `lazy:` markers and skips ignored dirs.
324 +- debt scanner flags missing upgrade trigger.
326 +Required harness tests:
328 +- extension loads in real Pi extension runtime.
329 +- agent-end diff scan notifies when a new `lazy:` marker appears.
330 +- commands registered: `lazy`, `lazy-review`, `lazy-audit`, `lazy-debt`, `lazy-gain`, `lazy-help`.
331 +- `/lazy ultra` appends a `lazy-mode` entry and updates status.
332 +- `before_agent_start` injects instructions when active and returns undefined when off.
333 +- skill alias commands send `/skill:<name>` immediately when idle and `followUp` when streaming.
334 +- `/lazy-debt` produces deterministic output without mutating files.
335 +- status gracefully does nothing when UI or theme is unavailable.
339 +- skill files pass `scripts/check_skills.mjs`.
340 +- README lists commands, settings, and install path.
341 +- no shell-specific code is used for scanner/config logic.
343 +Release gate: `mise run ci`.
345 +##
Same-or-better checklist 349 +- Always-on prompt injection.
350 +- Lite/full/ultra/off modes.
351 +- Session mode persistence.
352 +- Default mode config.
353 +- Equivalent `/lazy*` command set.
355 +- Status indication.
357 +- Safety boundaries and test-floor rules.
359 +Better than upstream Pi adapter:
361 +- TypeScript, typed internals, and Vitest harness tests aligned with this repo.
362 +- Pi settings namespace instead of defaulting to host-specific config files.
363 +- Branch-aware Pi session entries instead of process/global flag files.
364 +- Direct deterministic `/lazy-debt`, `/lazy-gain`, and `/lazy-help` commands.
365 +- Command argument completions for modes and note-like target args.
366 +- No CommonJS bridge to hook files.
367 +- No shell grep in user-facing logic.
368 +- No fragile subagent event timing; v1 intentionally has no subagent handoff.
370 +##
Risks and decisions 372 +- **Prompt weight:** always-on instructions add tokens every turn.
373 + Keep the injected block shorter than the full skill body while preserving safety rules.
374 +- **Review/audit are model tasks:** direct deterministic implementation would be brittle.
375 + Keep them as skill handoffs.
376 +- **Benchmarks:** do not claim current-repo savings.
377 + The gain card must state benchmark provenance.
379 +##
Open questions for user review 381 +1. Should `/lazy default <mode>` write Pi settings if an API exists, or only print the JSON to add?
382 +2. Should `/lazy-debt --write` be in v1, or deferred until someone asks?
384 +##
Implementation plan preview 386 +1. Add extension skeleton and exported skills.
387 +2. Implement mode/config/instruction modules with unit tests.
388 +3. Implement command registration, session replay, status, and prompt injection with harness tests.
389 +4. Implement direct debt/help/gain commands.
390 +5. Add README and root package skill export.
391 +6. Run `mise run fmt`, `mise run lint`, targeted tests, then `mise run ci`.