local-executor 0.1.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "local-executor",
+  "version": "0.1.0",
+  "description": "Set up a planner → local executor → auditor AI coding pipeline: installs Ollama, picks a right-sized open-weight model for your hardware, and installs the skill into Claude Code, Codex CLI, Cursor, and Windsurf.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "lex": "dist/cli.js",
+    "local-executor": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "ollama",
+    "local-llm",
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "ai-coding",
+    "agent",
+    "qwen",
+    "gemma",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Raghdkun/local-executor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Raghdkun/local-executor/issues"
+  },
+  "homepage": "https://github.com/Raghdkun/local-executor#readme",
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "commander": "^15.0.0",
+    "execa": "^9.6.1",
+    "picocolors": "^1.1.1",
+    "systeminformation": "^5.33.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.12",
+    "@types/node": "^22.20.1",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "local-executor contributors"
+}

package/skill/adapters/claude-code/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: local-executor-pipeline
+description: Three-role coding pipeline where Claude plans and writes tests, a local open-weight model via Ollama writes the code, and an Opus subagent audits the result. Use this whenever the user says "use the local model", "use the local executor", "hand this to the executor", "run the pipeline", "delegate the coding", mentions Ollama/Qwen/Gemma for a coding task, or wants to save cloud tokens by offloading implementation work to a local LLM.
+---
+
+# Local Executor Pipeline (Claude Code adapter)
+
+Read `{{LEX_CORE}}/PIPELINE.md` now and follow it. This file only covers what is specific to Claude Code.
+
+Installed by `local-executor` v{{LEX_VERSION}}. Executor model: `{{LEX_MODEL}}` (from `{{LEX_CONFIG}}`).
+
+## Running the scripts
+
+Use the Bash tool:
+
+```bash
+node "{{LEX_RUNTIME}}/check_local.mjs"
+node "{{LEX_RUNTIME}}/run_executor.mjs" --packet .lex/packet-1.md --out .lex/response-1.md
+```
+
+Write packets under `.lex/` in the repo (add it to `.gitignore` if it is not already) so the user can inspect them.
+
+## Inventory step (Step 1 in PIPELINE.md)
+
+- Skills: list `~/.claude/skills/` and `./.claude/skills/`; the ones already loaded in your context count too.
+- MCP tools: whatever `mcp__*` tools you see in your tool list. Prefer a docs MCP (e.g. context7) over guessing an API when writing the packet.
+
+## Audit step (Step 4 in PIPELINE.md)
+
+Spawn the auditor with the Task tool. It must be a **separate subagent** so its context contains only the audit prompt, the packet, the diff, and the test output:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  model: "opus",
+  description: "Audit local-executor diff",
+  prompt: <contents of {{LEX_CORE}}/audit-prompt.md with PACKET, DIFF, TEST_OUTPUT filled in>
+)
+```
+
+Never audit in your own context when the Task tool is available. The auditor may read the repo but must not edit it; say so in the prompt.
+
+## Escalation
+
+When PIPELINE.md says to escalate, do the task yourself in this same session and tell the user in one line why the executor could not finish.

package/skill/adapters/codex/AGENTS.block.md

@@ -0,0 +1,13 @@
+## Local executor pipeline (installed by local-executor v{{LEX_VERSION}})
+
+When the user says "use the local model", "use the local executor", "hand this to the executor", "run the pipeline", or wants to save cloud tokens on implementation work, follow `{{LEX_CORE}}/PIPELINE.md`. You are the **planner**: you write the plan and the tests; the local model (`{{LEX_MODEL}}`, configured in `{{LEX_CONFIG}}`) writes the code; a separate reviewer pass audits it.
+
+Codex-specific notes:
+
+- Check the executor: `node "{{LEX_RUNTIME}}/check_local.mjs"`.
+- Run a packet: `node "{{LEX_RUNTIME}}/run_executor.mjs" --packet .lex/packet-1.md --out .lex/response-1.md`. The script only talks to `127.0.0.1:11434`. If the sandbox blocks that call, ask for approval to run it outside the sandbox rather than disabling the sandbox globally.
+- Inventory (Step 1): skills live in `~/.codex/skills/` and in sections of this file; MCP servers are in `~/.codex/config.toml`.
+- Audit (Step 4): run a **second** Codex invocation with a fresh context so the reviewer has not seen your planning:
+  `codex exec --model <strongest model you have> "$(cat .lex/audit-1.md)"`
+  where `.lex/audit-1.md` is `{{LEX_CORE}}/audit-prompt.md` with PACKET, DIFF, and TEST_OUTPUT filled in. Paste its `VERDICT` back into your reasoning and act on it. If you cannot run a second invocation, do the audit in a separate pass and say that self-review is weaker.
+- Escalate per Step 5 and say why in one line.

package/skill/adapters/codex/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: local-executor-pipeline
+description: Plan and write tests here, let a local Ollama model ({{LEX_MODEL}}) write the code, then audit with a fresh reviewer pass. Use when the user says "use the local model", "use the local executor", "run the pipeline", or wants to save cloud tokens on implementation work.
+---
+
+Read `{{LEX_CORE}}/PIPELINE.md` and the "Local executor pipeline" section of `~/.codex/AGENTS.md`, then follow them. Scripts: `{{LEX_RUNTIME}}/check_local.mjs`, `{{LEX_RUNTIME}}/run_executor.mjs`. Config: `{{LEX_CONFIG}}`.

package/skill/adapters/cursor/local-executor.mdc

@@ -0,0 +1,19 @@
+---
+description: Local executor pipeline — plan and write tests in Cursor, let a local Ollama model ({{LEX_MODEL}}) write the code, audit in a fresh chat. Apply when the user says "use the local model", "use the local executor", "run the pipeline", or wants to save cloud tokens on implementation work.
+globs:
+alwaysApply: false
+---
+
+# Local executor pipeline (Cursor adapter, installed by local-executor v{{LEX_VERSION}})
+
+Read `{{LEX_CORE}}/PIPELINE.md` and follow it. You are the **planner**. The local model writes code; you never let it plan or decide scope.
+
+Cursor-specific notes:
+
+- Run scripts in the integrated terminal:
+  `node "{{LEX_RUNTIME}}/check_local.mjs"`
+  `node "{{LEX_RUNTIME}}/run_executor.mjs" --packet .lex/packet-1.md --out .lex/response-1.md`
+- Inventory (Step 1): other rules in `.cursor/rules/` and any MCP servers configured in Cursor settings. Use a docs MCP to get exact API facts into the packet.
+- Audit (Step 4): Cursor cannot spawn a subagent. Tell the user: "Opening a fresh chat for the audit so the reviewer has not seen my planning." Then open a **new chat** with the strongest available model, paste `{{LEX_CORE}}/audit-prompt.md` with PACKET, DIFF, and TEST_OUTPUT filled in, and bring the `VERDICT` back here. Do not audit in this chat unless the user declines; if so, say self-review is weaker.
+- Escalate per Step 5 and say why in one line.
+- Config: `{{LEX_CONFIG}}`. Change the model with `lex switch <tag>`, not by editing rules.

package/skill/adapters/windsurf/local-executor.md

@@ -0,0 +1,18 @@
+---
+trigger: model_decision
+description: Local executor pipeline — plan and write tests in Windsurf, let a local Ollama model ({{LEX_MODEL}}) write the code, audit in a fresh conversation. Apply when the user says "use the local model", "use the local executor", "run the pipeline", or wants to save cloud tokens on implementation work.
+---
+
+# Local executor pipeline (Windsurf adapter, installed by local-executor v{{LEX_VERSION}})
+
+Read `{{LEX_CORE}}/PIPELINE.md` and follow it. You are the **planner**. The local model writes code; you never let it plan or decide scope.
+
+Windsurf-specific notes:
+
+- Run scripts in the terminal:
+  `node "{{LEX_RUNTIME}}/check_local.mjs"`
+  `node "{{LEX_RUNTIME}}/run_executor.mjs" --packet .lex/packet-1.md --out .lex/response-1.md`
+- Inventory (Step 1): other rules in `.windsurf/rules/`, workflows in `.windsurf/workflows/`, and MCP servers configured in Windsurf. Use a docs MCP to get exact API facts into the packet.
+- Audit (Step 4): Cascade cannot spawn a subagent. Tell the user: "Starting a new conversation for the audit so the reviewer has not seen my planning." Then open a **new Cascade conversation** with the strongest available model, paste `{{LEX_CORE}}/audit-prompt.md` with PACKET, DIFF, and TEST_OUTPUT filled in, and bring the `VERDICT` back here. Do not audit in this conversation unless the user declines; if so, say self-review is weaker.
+- Escalate per Step 5 and say why in one line.
+- Config: `{{LEX_CONFIG}}`. Change the model with `lex switch <tag>`, not by editing rules.

package/skill/core/PIPELINE.md

@@ -0,0 +1,109 @@
+# Local Executor Pipeline
+
+You are the **planner**. A small local model running in Ollama is the **executor**. A strong model in a separate context is the **auditor**. Each role does one thing, and the handoffs between them are strict, because a small model is only reliable when its task is narrow and its output is checked by something stronger.
+
+```
+ user request
+      │
+      ▼
+ ┌─────────┐   task packet    ┌──────────────┐   diff + test log   ┌─────────┐
+ │ PLANNER │ ───────────────▶ │  EXECUTOR    │ ──────────────────▶ │ AUDITOR │
+ │ (you)   │                  │ (local LLM)  │                     │ (strong)│
+ └─────────┘ ◀─────────────── └──────────────┘ ◀─────────────────  └─────────┘
+      ▲          retry with            verdict: ACCEPT / REJECT + reasons
+      └──────────────────── apply or loop (max 3) ──────────────────┘
+```
+
+The local model is a cost saver, not a replacement. When it can't do the job within the limits below, you do the job.
+
+This file is agent-neutral. The adapter that loaded it (Claude Code skill, Codex AGENTS block, Cursor/Windsurf rule) tells you how to spawn the auditor in your environment. Files for this install live at:
+
+- Core docs: `{{LEX_CORE}}`
+- Runtime scripts and config: `{{LEX_RUNTIME}}`
+- Configured executor model: `{{LEX_MODEL}}` (read `{{LEX_CONFIG}}`; never hard-code a tag)
+
+## Step 0 — Make sure the executor exists
+
+Run:
+
+```
+node "{{LEX_RUNTIME}}/check_local.mjs"
+```
+
+It prints `READY`, `NOT RUNNING`, or `MISSING MODEL`, with the fix. If anything is missing, tell the user to run `npx local-executor` (or `lex doctor`). Do not pull models yourself without asking; downloads are several GB.
+
+## Step 1 — Inventory what you have (30 seconds, once per task)
+
+Before planning, list in one or two lines:
+
+- **Skills available on this machine** relevant to the task. Claude Code: `~/.claude/skills` and `./.claude/skills`. Codex: sections in `AGENTS.md` and `~/.codex/skills`. Cursor: `.cursor/rules`. Windsurf: `.windsurf/rules`. A test-runner skill, a repo-conventions skill, a docs skill — use them to write a better packet.
+- **MCP tools connected** to this agent that help: documentation lookup, issue tracker, database schema, browser. Use them during planning to get the facts the executor will need pasted into the packet.
+
+State which ones you will use for this task, e.g. "Using: context7 MCP for the Prisma API; repo's `testing` skill for the test command." If none apply, say "No extra skills/tools needed."
+
+The executor gets **no tools and no skills**. Everything it needs must be in the packet. Your inventory step is how you find that information; it is not something you hand off.
+
+## Step 2 — Plan (you)
+
+Turn the user's request into one or more **task packets**. A packet is the entire world the executor will see, so it has to be self-contained. Read `{{LEX_CORE}}/handoff-template.md` and follow it exactly.
+
+Rules that matter for a small model:
+
+- One packet = one file, or one function, or one tightly scoped change. If a request touches four files, that is four packets, run in dependency order.
+- **Write the tests first, yourself, before the executor sees anything.** Put them in the repo. The packet tells the executor which test command must pass. This is the single biggest lever on quality: the executor can't argue with a failing test.
+- Paste the relevant existing code into the packet verbatim. Do not describe it; the executor can't open files.
+- State conventions explicitly, and **always include the modern-practices block** for the target language from `{{LEX_CORE}}/modern-practices.md`: current stable language version, idiomatic patterns, no deprecated APIs, typed where the language supports it, explicit error handling, no `any` / `interface{}`-style escape hatches unless the packet justifies them.
+- Say what NOT to do (don't refactor, don't add dependencies, don't touch other files).
+
+## Step 3 — Execute (local model)
+
+Write the packet to a file (for example `.lex/packet-1.md` inside the repo, or a temp dir), then run:
+
+```
+node "{{LEX_RUNTIME}}/run_executor.mjs" --packet <packet.md> --out <response.md> [--apply --root <repo>]
+```
+
+The script sends the packet to Ollama with the system prompt in `{{LEX_CORE}}/executor-system-prompt.md`, which forces the executor to return only fenced code blocks tagged with file paths. It writes the raw response to `--out` and, with `--apply`, also writes each block to its file path under `--root` (creating a `.bak` backup alongside). Exit codes: `0` ok, `2` Ollama error, `3` no code blocks, `4` the executor declared it cannot do the task.
+
+Default flow: run without `--apply`, read the output, then apply and run the test command from the packet yourself. If tests fail, decide whether the failure is a planning error (fix the packet) or an execution error (retry, appending the failure output under `## Previous attempt failed`). Cap at **3 attempts per packet**.
+
+## Step 4 — Audit (strong model, separate context)
+
+Only once the tests pass. The auditor is **never the local model** and **never the same context that wrote the packet**. Use `{{LEX_CORE}}/audit-prompt.md`, filling in the packet, the diff, and the test output.
+
+- **Claude Code**: spawn a subagent with `model: opus` via the Task tool, with the audit prompt as its task.
+- **Codex CLI**: run a second `codex exec` invocation with the audit prompt as the task (a fresh context, ideally a stronger model via `--model`).
+- **Cursor / Windsurf**: they cannot spawn subagents. Open a fresh chat/composer, paste the audit prompt, and bring the verdict back. Tell the user you are doing this and why.
+- If none of the above is possible, do the audit yourself in a separate pass and say so; self-review is weaker.
+
+The auditor returns `ACCEPT` or `REJECT` with a numbered, severity-tagged list of issues. On `REJECT`, feed the issues back as a new executor attempt (counts toward the 3-attempt cap). On `ACCEPT`, apply the change (if not already applied) and move to the next packet.
+
+## Step 5 — Escalate when the pipeline can't finish
+
+You take over the task yourself, and log one line saying why, when any of these happen:
+
+- 3 attempts on a packet without passing tests and audit.
+- The packet would exceed ~6,000 tokens of pasted code even after splitting.
+- The executor returns prose instead of code twice in a row, or exits with code `4` (declared it cannot).
+- The task needs tools (network, DB, browser) during implementation, not just during planning.
+
+Example log line: `Escalating: 3 attempts on packet-2 (auth middleware); executor kept dropping the async error path. Doing it myself.`
+
+## Step 6 — Report
+
+When all packets are done, tell the user in a few sentences: what was changed, how many executor attempts it took, what the auditor flagged, and anything you had to do by hand. Don't paste the full diff unless asked.
+
+## When to skip the pipeline
+
+If the task is a one-line fix, a rename, or something you can do faster than writing a packet, just do it and mention that the pipeline wasn't worth invoking. The pipeline earns its overhead on medium tasks: implementing a spec'd function, filling in a module against tests, mechanical but non-trivial code.
+
+## Files in this install
+
+- `{{LEX_CONFIG}}` — model name, Ollama URL, context size, timeouts
+- `{{LEX_RUNTIME}}/check_local.mjs` — is everything installed and running?
+- `{{LEX_RUNTIME}}/run_executor.mjs` — send a packet, get code back, optionally apply
+- `{{LEX_CORE}}/handoff-template.md` — exact packet format for the executor
+- `{{LEX_CORE}}/executor-system-prompt.md` — the system prompt the executor runs under
+- `{{LEX_CORE}}/modern-practices.md` — per-language conventions block to paste into packets
+- `{{LEX_CORE}}/audit-prompt.md` — exact prompt for the auditor and its verdict format
+- `{{LEX_CORE}}/models.md` — which local model fits which hardware (generated for this machine)

package/skill/core/audit-prompt.md

@@ -0,0 +1,51 @@
+# Auditor prompt
+
+The auditor is a **strong model in a fresh context**: never the local executor, never the planner's own context. How you get a fresh context depends on your agent:
+
+- **Claude Code**: Task tool, `model: opus`, `subagent_type: general-purpose`, this prompt as the task.
+- **Codex CLI**: `codex exec --model <strongest available> "<this prompt>"` from the repo root (a second invocation, not the current one).
+- **Cursor / Windsurf**: open a new chat/composer and paste this prompt. Bring the verdict back to the planning chat.
+
+The auditor should have read access to the repo so it can look at neighboring code, but it must not edit anything. Fill in the three placeholders and send as the task.
+
+```
+You are auditing a code change written by a small local language model. The change already passes its tests. Your job is to catch what tests don't: correctness gaps, security issues, and code that will hurt later.
+
+## The task packet the executor received
+{PACKET}
+
+## The diff it produced
+{DIFF}
+
+## Test output
+{TEST_OUTPUT}
+
+Review the diff against the packet. Check, in this order:
+1. Correctness — does it actually satisfy the Goal, or just the tests? Look for edge cases the tests don't cover (empty input, None/null, unicode, concurrency, off-by-one).
+2. Scope — did it touch anything outside "Files you may change"? Did it violate any "Do NOT"?
+3. Safety — injection, unsafe deserialization, path traversal, secrets in code, unbounded resource use.
+4. Fit — does it match the stated conventions, including the modern-practices block, and the surrounding codebase? Any deprecated API, untyped escape hatch, or swallowed error is at least a major.
+5. Tests — are the packet's tests themselves adequate? If a critical case is missing, say which one.
+
+Respond with exactly this format:
+
+VERDICT: ACCEPT | REJECT
+
+ISSUES:
+1. [severity: blocker|major|minor] <file:line if applicable> — <one or two sentences, concrete, actionable>
+2. ...
+
+(If ACCEPT with no issues, write "ISSUES: none".)
+
+MISSING TESTS:
+- <test case description, or "none">
+
+Reject for any blocker. Accept with listed minors is fine. Do not rewrite the code yourself; describe the fix precisely enough that a small model can apply it.
+```
+
+## How the planner uses the verdict
+
+- `ACCEPT` → apply and move on. Add any "MISSING TESTS" to the repo if they're cheap.
+- `REJECT` → build a retry packet: copy the original, append the ISSUES list under `## Previous attempt failed`, and re-run the executor. Counts toward the 3-attempt cap.
+- If the auditor flags a **planning** problem (bad packet, inadequate tests), fix the packet yourself rather than retrying blindly.
+- Never skip the audit because "the tests pass". Passing tests is the entry ticket to the audit, not a substitute for it.

package/skill/core/executor-system-prompt.md

@@ -0,0 +1,34 @@
+You are a code executor. You receive a task packet and return code. Do exactly what the packet says. Nothing more.
+
+OUTPUT FORMAT (this matters most)
+- Reply with fenced code blocks only. No words before, between, or after them. No headings. No explanations.
+- Each block's info string is exactly: <language> path=<relative/file/path>
+- Each block holds the COMPLETE new contents of that file. Never a fragment. Never a diff.
+- One block per file you change. Only files listed under "Files you may change".
+
+RULES
+- Make the tests under "Tests that must pass" pass. Never edit the tests.
+- Follow "Conventions" exactly, including the modern-practices bullets. Use the stated language version. No deprecated APIs. No untyped escape hatches.
+- Do not refactor, rename, reorder, or reformat code the packet did not ask you to change.
+- Do not add dependencies unless the packet allows them.
+- If the packet has "Previous attempt failed", fix that specific failure and nothing else.
+- If the packet is impossible or contradictory, reply with exactly one block:
+  ```text path=EXECUTOR_CANNOT.md
+  <one to three lines saying what is missing or contradictory>
+  ```
+
+EXAMPLE OF A CORRECT REPLY (two files changed):
+
+```python path=src/utils.py
+def add(a: int, b: int) -> int:
+    """Return the sum of a and b."""
+    return a + b
+```
+
+```python path=src/__init__.py
+from .utils import add
+
+__all__ = ["add"]
+```
+
+That is the entire reply. Start your reply with three backticks.

package/skill/core/handoff-template.md

@@ -0,0 +1,65 @@
+# Task packet format
+
+The executor sees nothing but this document. Every packet uses this exact structure. Sections marked (required) must never be empty.
+
+```markdown
+# Task: <one-line title>
+
+## Goal (required)
+<2–4 sentences. What the code must do when finished. State the observable behavior, not the implementation.>
+
+## Files you may change (required)
+- path/to/file.py — <what changes here>
+
+You may NOT change any other file.
+
+## Conventions (required)
+- Language/version: <e.g. Python 3.12>
+- Style: <e.g. type hints on all functions, no print(), use logging>
+- Allowed dependencies: <e.g. stdlib only>
+- Naming: <anything the repo cares about>
+- Modern practices (required — copy the block for this language from modern-practices.md):
+  - <bullet 1>
+  - <bullet 2>
+  - ...
+
+## Existing code (required if the file exists)
+### path/to/file.py
+```python
+<full current contents, verbatim>
+```
+
+## Tests that must pass (required)
+Command: `<exact command, e.g. pytest tests/test_utils.py -q>`
+
+### tests/test_utils.py
+```python
+<full contents of the test file the planner wrote, verbatim>
+```
+
+## Do NOT
+- <refactor unrelated code>
+- <add new dependencies>
+- <change function signatures listed above>
+
+## Previous attempt failed (only on retry)
+Attempt <n> produced this test output:
+```
+<pasted failure output, trimmed to the relevant part>
+```
+Fix this specific failure.
+```
+
+## Why each section exists
+
+- **Goal** first, because small models anchor on whatever comes first.
+- **Files you may change** bounds the blast radius. Without it, executors "helpfully" rewrite neighbors.
+- **Existing code verbatim**: the executor cannot read the disk. If you summarize instead of pasting, it will hallucinate the parts you skipped.
+- **Tests verbatim**: this is the contract. The executor optimizes for making the tests pass, which is exactly what you want when you wrote the tests.
+- **Conventions → Modern practices** is mandatory. Small models default to whatever was most common in their training data, which is often years out of date. The block pins the language version, the idioms, and the escape hatches that are off limits.
+- **Do NOT** is more effective than positive instructions for small models. Be concrete.
+- **Previous attempt failed** turns a retry into a targeted fix rather than a fresh guess.
+
+## Sizing
+
+If the packet exceeds ~6,000 tokens of pasted code, it is too big for one executor call. Split it: either by file, or by extracting the specific function and its immediate dependencies.

package/skill/core/modern-practices.md

@@ -0,0 +1,61 @@
+# Modern-practices blocks
+
+Paste the block for the target language into the packet's **Conventions → Modern practices** list. Adjust versions to what the repo actually uses (check `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `*.csproj`, `Package.swift`). If the repo is older than the versions below, say so in the packet and pin to the repo's version; do not let the executor "upgrade" the project. Last reviewed: 2026-09-06.
+
+Every block is short on purpose: a small model follows five concrete bullets better than a page of guidance. Add one or two repo-specific bullets (formatter, import order, logging library) and stop.
+
+## TypeScript / JavaScript
+- TypeScript ≥ 5.9 (7.x if the repo uses it), `strict: true`. ESM (`import`/`export`), not CommonJS, unless the repo is CJS.
+- No `any`. Use `unknown` + narrowing, or precise types. No non-null assertions (`!`) without a comment.
+- `async`/`await`; never unhandled promises. Errors are thrown or returned as typed results, not swallowed.
+- Prefer `const`; no `var`. Optional chaining and nullish coalescing over manual checks.
+- Node ≥ 20 APIs: `fetch`, `node:fs/promises`, `node:path`, `structuredClone`. No `request`, no callbacks-style fs.
+- Tests: vitest or the repo's runner. Named exports. No default exports for libraries.
+
+## Python
+- Python ≥ 3.12 (3.11 minimum). Type hints on every function signature; `list[str]` / `X | None`, not `List`/`Optional`. `from __future__ import annotations` if the repo targets 3.9/3.10.
+- Dataclasses or Pydantic for structured data, not dicts passed around.
+- `pathlib.Path`, not `os.path`. f-strings, not `%` or `.format()`.
+- Explicit exceptions; never bare `except:`. Context managers for resources.
+- No mutable default arguments. No wildcard imports.
+- Tests: pytest, plain `assert`.
+
+## Go
+- Go ≥ 1.24 (1.22 minimum, for range-over-int and loop-var semantics). Errors are returned and wrapped with `fmt.Errorf("...: %w", err)`; never ignored with `_` unless justified in a comment.
+- `context.Context` as first parameter for anything that does I/O.
+- Generics where they remove duplication; interfaces small and defined at the consumer.
+- `slices`, `maps`, `log/slog` from the standard library. No `ioutil`.
+- Table-driven tests with `t.Run`.
+
+## Rust
+- Edition 2024 (2021 minimum). `Result<T, E>` with `?`; no `unwrap()`/`expect()` outside tests and `main`.
+- `thiserror` for library errors, `anyhow` only at binary boundaries (if the repo allows the dependency).
+- Borrow, don't clone, unless clarity demands it and a comment says so. No `unsafe` unless the packet allows it.
+- Clippy-clean at default level.
+
+## Java / Kotlin
+- Java ≥ 21 (records, sealed types, pattern matching for switch, virtual threads; 17 minimum). Kotlin ≥ 2.1 (K2 compiler, data classes, sealed interfaces, coroutines for async).
+- Immutability by default: `final` fields / `val`. `Optional` / nullable types instead of null checks scattered everywhere.
+- No raw types. No checked-exception swallowing.
+- JUnit 5 / Kotest.
+
+## Swift
+- Swift ≥ 6 with strict concurrency where the package enables it (5.9 minimum). `struct` by default, `class` only when reference semantics are needed. Value types `Sendable` where shared.
+- `async`/`await` and structured concurrency; no completion-handler APIs in new code.
+- `guard` for early exits; no force-unwraps (`!`) outside tests.
+- Swift Testing or XCTest per the repo.
+
+## C#
+- .NET ≥ 9 (8 LTS minimum), nullable reference types enabled, file-scoped namespaces, records for DTOs.
+- `async`/`await` end to end with `CancellationToken` parameters. No `.Result` / `.Wait()`.
+- Pattern matching and switch expressions. `IReadOnlyList<T>` on public surfaces.
+- xUnit.
+
+## Shell (when unavoidable)
+- Bash: `set -euo pipefail`, quote every variable, `[[ ]]` tests, no parsing `ls`.
+- PowerShell: `Set-StrictMode -Version Latest`, `$ErrorActionPreference = 'Stop'`.
+
+## Universal
+- Match the repo's existing formatter/linter config; do not introduce a new style.
+- Every public function has a one-line doc comment stating what it does and what it returns.
+- No commented-out code, no `TODO` in delivered code, no debug prints.

package/skill/runtime/check_local.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * Reports whether Ollama is running and has the configured model.
+ * Works on macOS, Linux, Windows. Exit 0 = ready; 1 = something missing.
+ *
+ * Usage: node check_local.mjs [--json]
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const configPath = join(here, "config.json");
+const json = process.argv.includes("--json");
+
+function report(status, message, extra = {}) {
+  if (json) console.log(JSON.stringify({ status, message, config: configPath, ...extra }));
+  else console.log(`${status}: ${message}`);
+}
+
+let config;
+try {
+  config = JSON.parse(await readFile(configPath, "utf8"));
+} catch (err) {
+  report("BROKEN CONFIG", `cannot read ${configPath}: ${err.message}. Re-run: npx local-executor`);
+  process.exit(1);
+}
+
+let tags;
+try {
+  const res = await fetch(`${config.ollama_url}/api/tags`, { signal: AbortSignal.timeout(3000) });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  tags = await res.json();
+} catch {
+  report(
+    "NOT RUNNING",
+    `ollama server not reachable at ${config.ollama_url}. Start it (open the Ollama app, or run: ollama serve) or install it: npx local-executor`,
+    { model: config.model },
+  );
+  process.exit(1);
+}
+
+const names = (tags.models ?? []).map((m) => m.name);
+const have = names.includes(config.model) || names.includes(`${config.model}:latest`);
+if (!have) {
+  report("MISSING MODEL", `${config.model} not pulled. Run: ollama pull ${config.model}`, {
+    model: config.model,
+    available: names,
+  });
+  process.exit(1);
+}
+
+report("READY", `ollama running at ${config.ollama_url} with model ${config.model}`, {
+  model: config.model,
+  available: names,
+});

package/skill/runtime/config.json

@@ -0,0 +1,10 @@
+{
+  "ollama_url": "http://localhost:11434",
+  "model": "qwen3.5:9b",
+  "fallback_model": "qwen3.5:4b",
+  "num_ctx": 16384,
+  "temperature": 0.1,
+  "keep_alive": "30m",
+  "timeout_seconds": 600,
+  "think": false
+}