atom-lite 0.4.1 → 0.6.2

package/skills/atom-lite-extensions/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: atom-lite-extensions
+description: "Build, load, and debug Atom-lite extensions (Pi-compatible). Use when creating an extension, registering tools/commands/providers, handling events, adding UI widgets, or troubleshooting extension loading. Covers the ExtensionAPI surface, trust, discovery, tiers, and examples."
+license: MIT
+---
+
+# Atom-lite Extensions
+
+Atom-lite hosts **unmodified Pi coding-agent extensions in-process**. An
+extension is a TypeScript/JavaScript module that exports a default (or
+`activate`) function receiving an `ExtensionAPI` (`pi`). It registers tools,
+commands, providers, models, widgets, and event handlers into Atom-lite's own
+runtime.
+
+Reference docs:
+- `docs/extensions.md` — discovery, trust, compatibility tiers, diagnostics.
+- `docs/adr/0011-pi-extensions-in-process.md` — architecture.
+- `src/extensions/types.ts` — full `ExtensionAPI` + registries.
+- `src/extensions/api.ts` — runtime implementation.
+- `tests/extensions/` — conformance fixtures.
+- Run `/extensions` and `/extensions doctor` inside atom-lite for live diagnostics.
+
+## Minimal extension
+
+```ts
+// my-ext.ts
+export default function (pi: any) {
+  pi.registerTool({
+    name: "greet",
+    label: "Greet",
+    description: "Return a greeting for a name.",
+    parameters: { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      return { content: [{ type: "text", text: `Hello, ${params.name}!` }] };
+    },
+  });
+
+  pi.registerCommand({
+    name: "hello",
+    description: "Say hello",
+    async run(ctx, args) {
+      pi.notify(`hello ${args}`, "info");
+    },
+  });
+
+  pi.on("tool_call", async (event) => {
+    // observe every tool call
+    pi.log(`tool_call: ${event?.name}`);
+  });
+}
+```
+
+Load it:
+
+```bash
+atom-lite -e ./my-ext.ts
+# or place under .agents/skills? no — extensions live in extension dirs, see Discovery
+```
+
+## Discovery
+
+Extensions are discovered from:
+- CLI paths: `-e` / `--extension PATH`.
+- Atom-lite user/project extension directories.
+- Pi discovery locations and `settings.json` / `package.json` `pi.extensions` manifests.
+
+Project-local extensions are **skipped until the project is trusted**. Interactive
+sessions prompt for approval; non-interactive runs skip untrusted ones. Trust
+decisions are stored in user config. Check trust with `pi.isProjectTrusted()`.
+
+## Module shape
+
+Both forms are accepted (migration-friendly):
+
+```ts
+export default function (pi) { /* ... */ }
+export async function activate(pi) { /* ... */ }
+```
+
+Pi host modules are aliased to Atom-lite's own copies, so use Pi-style imports:
+
+```ts
+import { Type } from "@sinclair/typebox";          // or "typebox"
+import { Text } from "@earendil-works/pi-tui";     // or "pi-tui"
+```
+
+Legacy `@mariozechner/*` specifiers also resolve. TypeScript loads without a
+build step (via `jiti`).
+
+## Tools
+
+```ts
+pi.registerTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "What the LLM sees.",
+  parameters: { /* JSON Schema / TypeBox */ },
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    // stream partial output:
+    onUpdate?.({ content: [{ type: "text", text: "partial..." }] });
+    return { content: [{ type: "text", text: "final result" }], details: { foo: 1 } };
+  },
+  // optional custom rendering (Tier 2):
+  renderCall: (args, theme, context) => new Text(`call ${args}`),
+  renderResult: (result, options, theme, context) => new Text(result.content[0]?.text ?? ""),
+});
+pi.unregisterTool("my_tool");
+pi.setActiveTools(["my_tool"]);
+```
+
+## Commands
+
+```ts
+pi.registerCommand({
+  name: "mycmd",
+  description: "Do something",
+  argumentHint: "[arg]",
+  async run(args, ctx) {
+    pi.appendEntry("mycmd_ran", { args });
+    const ok = await pi.confirm("Title", "Proceed?");
+    const name = await pi.input("Name", "placeholder");
+    const choice = await pi.select("Pick", ["a", "b"]);
+  },
+});
+pi.unregisterCommand("mycmd");
+```
+
+Commands become `/mycmd` in the palette and support autocomplete.
+
+## Events
+
+```ts
+const off = pi.on("assistant_delta", async (event, ctx) => { /* ... */ });
+pi.off("assistant_delta", handler);
+```
+
+Common events: `tool_call`, `tool_result`, `assistant_delta`, `assistant_text`,
+`thinking_delta`, `agent_start`, `agent_end`, `turn_start`, `turn_end`,
+`context_usage`, `model_switched`, `session_start`. Tier 3 events
+(session tree, forks) fail loudly.
+
+## UI
+
+```ts
+pi.ui.notify("hello", "info");          // info | warning | error
+pi.setStatus("myext", "status text");   // undefined clears
+pi.registerWidget("aboveInput", { id: "my-widget", location: "aboveInput", render: (width) => ["line1"] });
+pi.setWidget("key", ["line"], { placement: "aboveEditor" });
+pi.setFooter((tui, theme, data) => /* component */);
+pi.setHeader((tui, theme) => /* component */);
+pi.setTitle("my title");
+pi.setWorkingMessage("thinking...");
+pi.setWorkingVisible(true);
+pi.setWorkingIndicator({ frames: ["⠋","⠙"], intervalMs: 80 });
+pi.setHiddenThinkingLabel("reasoning");
+pi.getToolsExpanded(); pi.setToolsExpanded(true);
+```
+
+Dialogs: `pi.select`, `pi.confirm`, `pi.input` (shown above).
+
+## Session entries
+
+```ts
+pi.appendEntry("custom_type", { foo: 1 });
+const entries = pi.getSessionEntries({ type: "custom_type" });
+pi.getSessionManager();   // read model
+pi.getSession();          // { id }
+pi.getWorkspace();
+```
+
+## Providers & models
+
+```ts
+pi.registerProvider({
+  name: "myprovider",
+  // OpenAI-compatible mapping; OAuth/streamSimple are reduced-compat
+});
+pi.registerModel({ id: "mymodel", provider: "myprovider", ... });
+pi.unregisterProvider("myprovider");
+```
+
+## Exec & logging
+
+```ts
+const res = await pi.exec("git", ["status"], { cwd: pi.getWorkspace() });
+pi.log("debug message");
+```
+
+## Shortcuts, flags, autocomplete
+
+```ts
+pi.registerShortcut("ctrl+shift+x", { description: "do thing", handler: async (ctx) => {} });
+pi.registerFlag("myflag", { type: "boolean", default: false });
+const v = pi.getFlag("myflag");
+pi.addAutocompleteProvider((tui, theme) => ({ /* ... */ }));
+```
+
+## Renderers (Tier 2)
+
+```ts
+pi.registerToolRenderer((toolName, next) => ({ renderCall, renderResult }));
+pi.registerMessageRenderer("custom_type", (message, options, theme) => /* Component */);
+pi.registerEntryRenderer("custom_type", (entry, theme) => /* Component */);
+pi.registerMarkdownTransformer((markdown) => markdown);
+```
+
+## Compatibility tiers
+
+- **Tier 1 (works today):** discovery, trust, TS loading, tools, commands, events,
+  session entries/read model, status/notify/dialogs/widgets/overlays, exec,
+  provider/model registration (OpenAI-compatible).
+- **Tier 2 (staged):** renderers, markdown transformers, shortcuts, flags,
+  autocomplete, custom footer/header/title, working indicator, thinking label.
+- **Tier 3 (deferred, fail loudly):** session tree/forks, codemode, MCP server
+  registration, OAuth providers, virtualModel, RPC mode, custom editors.
+
+Reduced-compat features (OAuth, `streamSimple`, classifiers, image generation,
+`refreshModels`) emit warnings rather than failing.
+
+## Diagnostics
+
+Inside atom-lite:
+- `/extensions` — list discovered extensions + load status.
+- `/extensions doctor` — per-extension tools/commands/errors.
+
+## Tips
+
+- Keep extensions dependency-free or bundle deps; host aliases cover Pi modules.
+- Use `pi.appendEntry` for persisted state instead of module globals.
+- Trust project extensions before they load (`pi.isProjectTrusted()`).
+- Reload with `/reload` (or restart) after edits; module caching is disabled.
+- Test against `tests/extensions/` conformance fixtures.
+
+## Links
+
+- Docs: `docs/extensions.md`
+- ADR: `docs/adr/0011-pi-extensions-in-process.md`
+- Types: `src/extensions/types.ts`
+- Runtime: `src/extensions/`
+- Pi extension API reference (installed): `~/.pi/agent/install/releases/1.4.0/node_modules/@earendil-works/pi-coding-agent/dist/core/extensions/types.d.ts`

package/skills/caveman/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: caveman
+description: >
+  Terse caveman voice: answer first, fluff gone, every technical fact kept.
+  Use for /caveman, "caveman mode", "talk like caveman", "be brief", "less
+  tokens". Stays on until "stop caveman" or "normal mode".
+---
+
+# caveman
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+Caveman is a voice, not broken grammar. Reader pays per token and reads in a terminal. Every word earns its place. Every fact survives.
+
+## Persistence
+
+Every response, whole session, until user says "stop caveman" or "normal mode". Unsure if still on? It is. Confirm the switch-off in one line.
+
+`/caveman ultra` and `/caveman wenyan` are aliases: follow the `ultracave` or `megacave` skill instead of this one. `/caveman status` reports the mode and changes nothing. Relay the hook's `Caveman mode: <mode>` value when present. No hook value (host without hooks): report the mode you followed before this command, or `off` if caveman was turned off or never active, plus `(not tracked by this host)`. Example: `Caveman mode: caveman (not tracked by this host)`. Loading this skill to answer status is not activation. Never infer a mode from the configured default.
+
+## Why
+
+1. Every output token is billed and read. Filler costs twice.
+2. Code, commands, paths, numbers, errors are the payload. One changed character breaks them.
+3. Ceremony is expensive, grammar is cheap. "Sure, I'd be happy to help" is ten tokens. "the" is one.
+4. A dropped negation costs more than every token saved. Clarity beats compression.
+
+## Rules
+
+### 1. Answer first
+
+Answer, then reason, then next step. Pattern: `[thing] [action] [reason]. [next step].`
+
+Bad: "Sure! I'd be happy to help. The issue you're experiencing is likely caused by..."
+Good: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+### 2. Kill ceremony
+
+No greeting, hedging, pleasantries, recap, or closer. No "Sure!", "Let me", "I'll now", "Hope this helps". No just/really/basically/actually/simply.
+
+### 3. Short word
+
+"fix" not "implement a solution for". Standard acronyms fine (DB, API, HTTP). Invented abbreviations not (cfg, impl, fn): same tokens, harder read. No arrows.
+
+### 4. Articles optional, meaning never
+
+Drop a/an/the when the sentence still reads in one pass. Fragments fine. Never drop not/never/no/only/except. Numbers and units exact.
+
+Bad: "Migration drop column backup first."
+Good: "Back up first. Then run migration: it drops the column."
+
+### 5. One idea per sentence
+
+ASD-STE100 is the floor: 20 words max, active voice, imperative for instructions, one term per thing, pronoun only with an obvious referent. Compression and clarity conflict? Clarity wins.
+
+### 6. Payload verbatim
+
+Code blocks unchanged. Commands, paths, API names exact. Errors quoted exact, shortest decisive line only. Code change shown in chat: changed lines plus 1-2 lines of context, not the whole file. Whole file only if the user asks, the file is new, or most of it changes. Existing comments in files you edit are payload too: never delete or shorten one you were not asked to change.
+
+### 7. Tool runs: bounded status
+
+No text between routine calls. One line before a multi-step run, one line per phase change, one line with the result at the end. Otherwise text before a call only to clarify, warn, or disambiguate.
+
+### 8. User's language
+
+Compress the style, not the language. An explicit reply-language instruction wins. Never switch because of quoted text. Technical terms and errors stay verbatim. Particles and case markers are grammar, not filler.
+
+### 9. Never perform caveman
+
+No "caveman mode on", no "me think", no "Caveman:" prefix, no normal answer plus caveman copy. No decorative tables or emoji. Never add a word to sound caveman. Caveman phrasing not shorter than plain? Use plain.
+
+## When to break the rules
+
+Plain prose, then resume:
+
+1. Security warning.
+2. Irreversible action. Confirm in full sentences first.
+3. Step order a fragment could scramble.
+4. User confused or repeats the question.
+5. Anything persisted outside chat: code, comments, commits, docs, issues, PRs, tickets, memory files, third-party messages. `/caveman-compress` exempt.
+6. Harness asks for a status line or confirmation. Give it. Harness decides *when* you speak, caveman decides *how*.
+7. You ask the user a question or offer options. Full sentences, so the answer comes back right first time.
+
+## Pre-send check
+
+1. First sentence announces what you will do? Delete.
+2. Last sentence recaps or offers help? Delete.
+3. Every not/never/no/only present? Every code span, path, number, error verbatim?
+4. Any sentence with two readings? Make it a full sentence.

package/skills/code-review/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: code-review
+description: >
+  Review code changes against repository standards and the originating spec.
+  Use for "review this PR", "review the diff", "code review", or before merging.
+---
+
+# Code Review
+
+Two-axis review of a change. Run both axes and report them separately.
+
+## Axes
+
+1. **Standards** — does the code follow this repo's documented conventions?
+   Sources: `AGENTS.md`, `CONTRIBUTING.md`, `docs/adr/*`, TypeScript strict mode,
+   NodeNext ESM, named exports, no new runtime deps without discussion.
+   Also apply the smell baseline: mysterious name, duplicated code, feature envy,
+   data clumps, primitive obsession, repeated switches, shotgun surgery,
+   divergent change, speculative generality, message chains, middle man,
+   refused bequest. A documented repo standard always overrides a smell.
+
+2. **Spec** — does the code implement what the issue/spec asked for?
+   Find the spec under `.scratch/<feature>/spec.md` or the referenced issue.
+
+## Process
+
+1. Pin the fixed point: `git diff <base>...HEAD` (three-dot). List commits.
+2. Identify standards sources and the spec source.
+3. For each file/hunk, report:
+   - Standards: hard violations (cite file + rule) and judgement-call smells.
+   - Spec: missing/partial requirements, scope creep, wrong-looking implementations.
+   Quote the spec line for each spec finding.
+4. Aggregate under `## Standards` and `## Spec` headings. Do not merge axes.
+
+## Output format
+
+- `## Standards` — findings per file/hunk, hard vs judgement.
+- `## Spec` — findings keyed to spec lines.
+- One-line summary per axis: count + worst issue.
+
+## Rules
+
+- Skip anything tooling enforces (tsc, tests, lint).
+- Smells are judgement calls, never hard violations.
+- Report facts, not opinions; cite paths and lines.
+- Small, reviewable findings are preferred over exhaustive nitpicks.

package/skills/optimization/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: optimization
+description: >
+  Optimize code for performance and efficiency while preserving behavior.
+  Use for "optimize", "make faster", "reduce memory", "performance".
+---
+
+# Optimization
+
+Expert performance engineer. Maximize speed/efficiency without changing observable behavior, APIs, return values, errors, side effects, ordering, or compatibility.
+
+## Strategy
+
+1. Understand implementation and hot paths.
+2. Find real bottlenecks (profile/analyze), not guesses.
+3. Fix algorithmic complexity before micro-optimizations.
+4. Cut allocations, copies, parsing/serialization, redundant I/O, repeated work.
+5. Improve data structures, caching, batching, concurrency where safe.
+6. Prefer small, safe, high-impact changes over risky rewrites.
+
+## Constraints
+
+- Never change behavior, validation, error handling, or edge cases.
+- Never weaken type safety or security.
+- Never introduce races or observable reordering.
+- Never edit tests to fit a change.
+- No speculative complexity without measurable gain.
+- Behavior preservation always beats performance.
+
+## Verification
+
+Before: understand behavior, find tests/benchmarks, establish baseline.
+After: run tests/typecheck/build; compare baseline; check edge cases and diff.
+
+No tests/benchmarks? State what is unverified.
+
+## Execution
+
+Work autonomously. Keep investigating until further gains are negligible, unsafe, or unjustified.
+
+## Report
+
+Provide concise, evidence-based summary:
+
+- Changes made
+- Bottlenecks eliminated
+- Before/after metrics (only measured)
+- Verification status
+- Limitations
+
+Use actual numbers only. If unmeasured, say "Not benchmarked" or "Expected benefit". If no improvement, say so.