@wular/coder 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/coder",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Delegating coding-agent runtime",
   "type": "module",
   "bin": {
@@ -22,7 +22,6 @@
     "dist",
     "plugins",
     ".claude-plugin",
-    ".agents",
     "README.md",
     "docs"
   ],

package/plugins/agents/skills/coder/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: coder
+description: Use Coder for any coding, implementation, or investigation task - features, fixes, refactors, debugging, tests, code questions. You orchestrate, never implement yourself; dispatch through the `coder` CLI, one coder per focused goal, fanning out many coders in parallel as the work needs.
+---
+
+# Coder dispatch
+
+You dispatch coding tasks through the `coder` runtime instead of implementing them yourself. By default the runtime picks the engine from its configured chain; flags like `--agent`/`--model`/`--effort` override it.
+
+If `coder` is not on PATH, install it yourself without asking (`npm install -g @wular/coder`). Assume nothing about setup state - the user may or may not have run setup. When a dispatch fails because engines are missing or logged out, run `coder setup-host` and follow its output: it checks engines and auth, seeds the config, refreshes this skill, auto-updates codex when too old for the default model, and prints the exact fix for anything not ready (safe to re-run anytime). Ask the user before installing an engine CLI or changing auth; if setup updated codex, tell the user to restart their codex session.
+
+## Dispatching a task
+
+- If your harness sandboxes terminal commands or asks approval for them (Codex does both), run every `coder` command with escalated/approved permissions - outside the sandbox, justification: Coder is a supervisor - it spawns engines, keeps state in `~/.coder`, and enforces its own sandbox and approval policy on the task. Never retry a blocked `coder` call inside a (stricter) sandbox or with HOME/state env workarounds.
+- One coder per focused goal. When the work splits into independent parts, decompose it and dispatch each part as its own `coder task run` call - fan out a wide web of coders running in parallel, not one giant dispatch. Give each coder a self-contained goal with all context - overview, file paths, constraints (read-only, git rules). Run independent tasks concurrently; use `steer` to continue a single coder's thread.
+- Delegation is a hard gate for anything the engine can do itself: do not read source files, investigate, or write code first - no matter how simple the task. Fold into the task text whatever only you have - conversation context, results from tools the engine lacks. The coder worker runs with plugins disabled (no skills, MCP, or connectors), so include any context only a plugin or MCP tool of yours produced.
+- Compose one self-contained task text (goal, relevant paths, constraints) and dispatch it. It backgrounds by default: the runtime does a startup check and prints a task id (or errors / hands off, see exit codes):
+
+  ```bash
+  coder task run "<task text>"
+  ```
+
+  Fetch the answer with `coder task result <task-id> --wait` - it blocks until the task finishes, then prints only the final result (keeps your context clean). Only use `--wait` when your harness can run it in a **background shell** (so it does not block you); without one, poll `coder task result <task-id>` (no `--wait`) until it is done. Or skip the two steps and block on the run itself with `--wait` on `coder task run`.
+
+- A `--wait` (on `run` or `result`) exits **4** when the task is waiting on a permission approval: relay the approval to the user, apply their decision with `coder approve <task-id> <approval-id> [--deny]`, then re-fetch with `coder task result <task-id> --wait`. (Unanswered approvals auto-deny after 120s and the task moves on.)
+
+- `coder task run` exits after its startup check. Exit 0: the task started - relay the task id and fetch its result (above). Exit 1: it failed to start or the turn failed - report it, do not retry or fall back yourself. Exit 3: no engine in the chain could start and stdout carries a `run-native-subagent` payload - see below.
+- When the first engine can't start (auth, quota, rate limit), the runtime automatically falls back to the next engine in the chain, runs the same task on it, and still exits 0 - so just fetch the result. If the failure mentions a usage-limit reset time, relay that to the user.
+- Engine, model, and effort come from config; add `--agent` / `--model` / `--effort` when the user asks or it is unambiguous from context (agents: `codex`, `claude`; codex models: `spark`, `luna`, `terra`, `sol`; claude models: `opus`, `sonnet`, `fable`; efforts: `low|medium|high`).
+  - `spark` is only for the very lightest tasks (formatting, renames, quick lookups) - very fast and very cheap. It runs on a separate quota, so reach for it when the others hit a usage limit; it may still run once they are exhausted.
+- Permissions default to auto mode (workspace-write + policy-answered escalations). Pass `--permissions read-only` when the task is read-only; `--permissions workspace-write` to forbid any escalation beyond the project.
+- A background dispatch prints a task id plus its result/steer/stop commands. Relay them and fetch the result (above) rather than polling.
+
+## Last resort: run-native-subagent payload (exit 3)
+
+When no coder engine can start (missing binaries, auth, quota across the whole chain), the runtime exits 3 with a JSON payload (`fallback.action: "run-native-subagent"`). Mention the failure to the user (including any limit-reset time). If your harness has a subagent facility, spawn one subagent whose prompt is the payload's `task` verbatim, prefixed with: "NEVER run git write operations (commit, checkout, stash, reset, push, etc.); leave changes uncommitted." If the payload's `permissions` is not `auto`, append it: `read-only` means investigate and report without modifying anything; `workspace-write` means never touch anything outside the workspace. Relay its output when it completes. If your harness has no subagent facility, report the failure and stop - never implement the task yourself.
+
+## Supervision loop
+
+With coders running in the background, don't fire-and-forget: check in on them recurrently with whatever scheduling facility your harness has (interval by the work's pace, 10m default); without one, check between your other steps. Each tick: `coder task list`, fetch finished results, dispatch newly unblocked coders, steer stuck ones, stop off-track ones, surface pending approvals. Stop when all tasks are done and relayed.
+
+## Controlling tasks
+
+- Continue prior work ("keep going", "apply the top fix"): `coder task steer <task-id> "<follow-up>"`.
+- Inspect: `coder task result <task-id>` (status + answer; add `--wait` to block until done) and `coder task list`. (`coder task stream <task-id>` streams the live progress log - to watch/debug in special cases, generally not for you to consume.)
+- Interrupt: `coder task stop <task-id>`.
+- If status shows `pendingApprovals`, surface them to the user; apply their decision with `coder task approve <task-id> <approval-id> [--deny]`.
+
+## Hard rules
+
+- Forward task text verbatim in `steer` follow-ups - never rewrite or summarize what the user asked for.
+- Tell every coder to never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.) and to leave changes uncommitted.
+- Pass the user's constraints (read-only, scoped paths) into each coder's task text, and honor them over your own preferences.

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "coder",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Delegate coding tasks to a Coder subagent. Your main context stays clean.",
   "author": {
     "name": "muzam1l"

package/plugins/claude/skills/handle/SKILL.md

@@ -5,13 +5,13 @@ description: Use Coder for any coding, implementation, or investigation task - f
 
 # Coder dispatch
 
-You dispatch coding tasks through the `coder` runtime instead of implementing them yourself. By default the runtime picks the engine from its configured chain; Flags like `--agent`/`--model`/`--effort` override it.
+You dispatch coding tasks through the `coder` runtime instead of implementing them yourself. By default the runtime picks the engine from its configured chain; flags like `--agent`/`--model`/`--effort` override it.
 
-If `coder` is not on PATH, install it yourself without asking (`npm install -g @wular/coder`), then continue; suggest the user run `/coder:setup` to configure the engines and chain.
+If `coder` is not on PATH, install it yourself without asking (`npm install -g @wular/coder`). Assume nothing about setup state - the user may or may not have run setup. When a dispatch fails because engines are missing or logged out, run `coder setup-host claude` and follow its output: it checks engines and auth, seeds the config, installs the host plugin, auto-updates codex when too old for the default model, and prints the exact fix for anything not ready (safe to re-run anytime). Ask the user before installing an engine CLI or changing auth; if setup updated codex, tell the user to restart their codex session. For a guided setup, suggest `/coder:setup`.
 
 ## Dispatching a task
 
-- One coder per focused goal. When the work splits into independent parts, decompose it and dispatch each part as its own background `coder task` - fan out a wide web of coders running in parallel, not one giant dispatch. Give each coder a self-contained goal with all context - overview, file paths, constraints (read-only, git rules). Run independent tasks concurrently; use `steer` to continue a single coder's thread.
+- One coder per focused goal. When the work splits into independent parts, decompose it and dispatch each part as its own `coder task run` call - fan out a wide web of coders running in parallel, not one giant dispatch. Give each coder a self-contained goal with all context - overview, file paths, constraints (read-only, git rules). Run independent tasks concurrently; use `steer` to continue a single coder's thread.
 - Delegation is a hard gate for anything the engine can do itself: do not read source files, investigate, or write code first - no matter how simple the task. Fold into the task text whatever only you have - conversation context, results from tools the engine lacks. The coder worker runs with plugins disabled (no skills, MCP, or connectors), so include any context only a plugin or MCP tool of yours produced.
 - Compose one self-contained task text (goal, relevant paths, constraints) and dispatch it. It backgrounds by default: the runtime does a startup check and prints a task id (or errors / hands off, see exit codes):
 
@@ -19,7 +19,7 @@ If `coder` is not on PATH, install it yourself without asking (`npm install -g @
   coder task run "<task text>"
   ```
 
-  Fetch the answer with `coder task result <task-id> --wait` - it blocks until the task finishes, then prints only the final answer (keeps your context clean). Run it as a **background Bash call** so it does not block you and you are re-invoked on completion:
+  Fetch the answer with `coder task result <task-id> --wait` - it blocks until the task finishes, then prints only the final result (keeps your context clean). Run it as a **background Bash call** so it does not block you and you are re-invoked on completion:
 
   ```bash
   coder task result <task-id> --wait   # Bash run_in_background: true
@@ -29,7 +29,8 @@ If `coder` is not on PATH, install it yourself without asking (`npm install -g @
 
 - A `--wait` (on `run` or `result`) exits **4** when the task is waiting on a permission approval: relay the approval to the user, apply their decision with `coder approve <task-id> <approval-id> [--deny]`, then re-fetch with `coder task result <task-id> --wait`. (Unanswered approvals auto-deny after 120s and the task moves on.)
 
-- `coder task run` exits after its startup check. Exit 0: the task started - relay the task id and fetch its result (above). Exit 1: it failed to start - report it, do not retry or fall back yourself. Exit 3: no engine in the chain could start and stdout carries a `run-native-subagent` payload - see below. (The runtime runs every engine itself, claude included, and falls back through its configured chain on startup failures - never fall back by implementing the task yourself.)
+- `coder task run` exits after its startup check. Exit 0: the task started - relay the task id and fetch its result (above). Exit 1: it failed to start or the turn failed - report it, do not retry or fall back yourself. Exit 3: no engine in the chain could start and stdout carries a `run-native-subagent` payload - see below.
+- When the first engine can't start (auth, quota, rate limit), the runtime automatically falls back to the next engine in the chain, runs the same task on it, and still exits 0 - so just fetch the result. If the failure mentions a usage-limit reset time, relay that to the user.
 - Engine, model, and effort come from config; add `--agent` / `--model` / `--effort` when the user asks or it is unambiguous from context (agents: `codex`, `claude`; codex models: `spark`, `luna`, `terra`, `sol`; claude models: `opus`, `sonnet`, `fable`; efforts: `low|medium|high`).
   - `spark` is only for the very lightest tasks (formatting, renames, quick lookups) - very fast and very cheap. It runs on a separate quota, so reach for it when the others hit a usage limit; it may still run once they are exhausted.
 - Permissions default to auto mode (workspace-write + policy-answered escalations). Pass `--permissions read-only` when the task is read-only; `--permissions workspace-write` to forbid any escalation beyond the project.

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "coder",
   "displayName": "Coder",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Delegate coding tasks to a Coder subagent. Your main context stays clean.",
   "author": {
     "name": "muzam1l"

package/plugins/cursor/README.md

@@ -2,91 +2,57 @@
 
 # Coder
 
-### Delegate the coding. Keep your context.
+**Delegate coding to subagents of any model from your favorite harness.**
 
 </div>
 
-One runtime that hands your coding tasks to the best engine available and lets you steer, inspect, or stop any task while it works.
-
-Plugs into Claude Code or Codex to enable the harness with Coder instances.
-
 ## Why Coder
 
-- **A clean main thread.** Installed in Claude Code or Codex, dispatch is a single command from your session; the actual coding runs in a Coder subagent. File dumps, test output, and retries stay there; only the outcome returns to your conversation.
-- **Fast dispatch.** Coder keeps a single Codex engine warm in the background and hands tasks to it directly, instead of booting the CLI for every request. A handoff starts in seconds.
-- **Unified permissions.** One permission model across agents, with three modes: **Read-only**, **Workspace-write**, and **Auto**. Auto is the default: safe commands run, dangerous ones are blocked, and anything in between is brought to you for a yes/no.
-- **Tasks you can steer.** Every dispatch is a task. Check on it, read its result, give it follow-up instructions, or stop it, all by id, while it keeps working in the background.
-- **Graceful fallback.** If Codex can't start (auth, usage limits, not installed), the task flows to a Claude subagent with the same instructions. You configure the chain and the default model and effort for each agent.
-- **Any model, anywhere.** Codex can point at local models (Ollama, LM Studio, and other OpenAI-compatible endpoints) and third-party providers, so Coder can run your tasks on those too - not just the hosted defaults. That opens up the whole scope of engines you can delegate to.
+- **Cross-harness.** One runtime, every host. The same subagents and models from Claude Code, Codex and more.
+- **Cross-model.** Codex, Claude, any OpenAI-compatible endpoint, or local models. Pick per task.
+- **Clean context.** Your conversation stays about intent and orchestration; implementation details live in the subagents.
+- **Fast dispatch.** Handoffs are instant, and light enough to spin up a large number of subagents at once.
+- **Steerable tasks.** Full visibility into every task, from live progress to mid-run course corrections.
+- **Unified permissions.** Three modes across all engines: _Read-only_, _Workspace-write_, and _Auto_.
 
 ## Get started
 
-Coder runs your tasks on an **engine CLI** - it needs at least one of the [codex CLI](https://github.com/openai/codex) (`npm install -g @openai/codex`, then `codex login`) or the [Claude Code CLI](https://github.com/anthropics/claude-code) (`npm install -g @anthropic-ai/claude-code`, then `claude auth login`) installed and logged in. `coder setup-host` reports which are ready; if none is, install one of them to run tasks.
-
-Follow the install host specific guides below, then you can ask like:
-
-> Use Coder to explain the directory structure of the workspace.
-
-You can also add this to CLAUDE.md.
-
-> Always use Coder for all implementation and system exploring tasks.
-
-The work happens in the engine, and your session gets the result. Codex is the primary engine when available, with a Claude subagent as fallback.
-
-### Cursor
+**1. Install a host plugin**:
 
 ```
 /add-plugin Coder
 ```
 
-### Claude Code
+Or from the shell (installs the same skill via the Agent Skills dir, `~/.agents/skills`):
 
-```
-/plugin marketplace add muzam1l/coder
-
-/plugin install coder@coder-plugins
-
-/reload-plugins
-
-/coder:setup
-```
-
-Or from the shell:
-
-```
+```bash
 npm install -g @wular/coder
-coder setup-host claude
+coder setup-host agents
 ```
 
-### Codex
+**2. Connect at least one engine.** Either an engine CLI, logged in, to use that subscription:
 
-```
-codex plugin marketplace add muzam1l/coder
-codex plugin add coder@coder-plugins
+```bash
+npm install -g @openai/codex && codex login
+# and/or
+npm install -g @anthropic-ai/claude-code && claude auth login
 ```
 
-Or from the npm directly:
+Or a local/provider model of your own (see [Bring your own model](docs/custom-models.md)). `coder setup-host` checks what's ready.
 
-```
-npm install -g @wular/coder
-coder setup-host codex
-```
+**3. Ask your host to use it:**
 
-Note: Codex 'Approve for me' just disables invoking CLI agents, so just use 'Ask for approval'/'Full Access' when using Codex/ChatGPT app as host.
+> Use Coder to explain the directory structure of the workspace.
 
-## Staying up to date
+Or make it the default in AGENTS.md/CLAUDE.md:
 
-```bash
-coder upgrade
-```
-
-It updates the CLI through whichever package manager installed it (npm, pnpm, yarn, or bun, auto-detected) and refreshes the host plugins to match. Narrow it with `--cli-only`, `--plugins-only`, `--codex`, `--claude`, or force a manager with `--pm <npm|pnpm|yarn|bun>`.
+> Always use Coder for all implementation and system exploring tasks.
 
-Set `CODER_NO_UPDATE_CHECK=1` to silence the update notice.
+Recommended setup: Claude Code as host (fable low/medium) and Codex (terra) as engine - best for performance and cost distribution.
 
 ## Configuration
 
-Machine defaults live in `~/.coder/config.json`; drop a `coder.config.json` in a repo to override per project.
+Machine defaults live in `~/.coder/config.json`; a `coder.config.json` in a repo overrides per project.
 
 ```json
 {
@@ -94,26 +60,35 @@ Machine defaults live in `~/.coder/config.json`; drop a `coder.config.json` in a
   "agents": {
     "codex": { "model": "terra", "effort": "high", "permissions": "auto" },
     "claude": { "model": "opus", "effort": "medium", "permissions": "auto" }
+  },
+  "models": {
+    "qwen": { "baseUrl": "http://localhost:11434/v1", "model": "qwen2.5-coder:32b" }
   }
 }
 ```
 
+## Staying up to date
+
+```bash
+coder upgrade
+```
+
+Updates the CLI through whichever package manager installed it and refreshes the host plugins to match. See `coder upgrade --help` for narrowing flags. Set `CODER_NO_UPDATE_CHECK=1` to silence the update notice.
+
 ## Advanced usage
 
-You rarely need these - the agent drives tasks itself - but you can run them. Task commands live under `coder task <sub>`; the common ones have a top-level shortcut. Full docs: `coder --help`, `coder task <sub> --help`.
+You rarely need these - the host agent drives tasks itself - but everything is scriptable:
 
 ```bash
-coder run "<text>"                # dispatch a task (--wait to block for the answer)
-coder result [task-id]            # status + final answer (--wait blocks until done)
-coder list [--all|--stopped]      # list tasks (running by default)
-coder task steer <id> "<text>"    # continue a task with new instructions
-coder task stop <id>              # interrupt it
-coder task stream [id]            # watch the live progress log (you/debugging)
-coder task archive <id>           # archive a session (--all-stopped for all finished)
-coder task delete <id>            # delete a session (--all-archived for all archived)
-coder task approve <id> <appr>    # answer an escalated permission (--deny)
+coder run "<text>"                     # dispatch a task (--wait to block for the answer)
+coder list                             # list running tasks (--all for running & stopped)
+coder result [task-id]                 # status + final answer (--wait blocks until done)
+coder task steer <task-id> "<text>"    # continue a task with new instructions
+coder task stop <task-id>              # interrupt it
+coder task stream [task-id]            # watch the live progress log
+coder task approve <task-id> <appr-id> # answer an escalated permission (--deny)
 ```
 
-`run`/`list`/`result`/`stream` are shortcuts for the `task` subcommand. Any `[task-id]` defaults to the most recent task and accepts a unique prefix.
+Any `[task-id]` defaults to the most recent task.
 
-Run flags (`run`/`steer`): `--wait` (foreground), `--agent codex|claude`, `--model spark|luna|terra|sol|opus|sonnet|fable`, `--effort low|medium|high`, `--permissions read-only|workspace-write|auto`, `--resume <task-id>`, `--json`.
+Full docs: `coder --help`.

package/plugins/cursor/skills/coder/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: coder
+description: Use Coder for any coding, implementation, or investigation task - features, fixes, refactors, debugging, tests, code questions. You orchestrate, never implement yourself; dispatch through the `coder` CLI, one coder per focused goal, fanning out many coders in parallel as the work needs.
+---
+
+# Coder dispatch (Cursor host)
+
+You dispatch coding tasks through the `coder` runtime instead of implementing them yourself. By default the runtime picks the engine from its configured chain; flags like `--agent`/`--model`/`--effort` override it.
+
+If `coder` is not on PATH, install it yourself without asking (`npm install -g @wular/coder`). Assume nothing about setup state - the user may or may not have run setup. When a dispatch fails because engines are missing or logged out, run `coder setup-host` and follow its output: it checks engines and auth, seeds the config, auto-updates codex when too old for the default model, and prints the exact fix for anything not ready (safe to re-run anytime; no host plugin to install - Cursor gets this skill from its marketplace). Ask the user before installing an engine CLI or changing auth; if setup updated codex, tell the user to restart their codex session.
+
+## Dispatching a task
+
+- `coder` commands are safe to run in the terminal - the runtime is a supervisor: it spawns engines, keeps state in `~/.coder`, and enforces its own OS sandbox and approval policy on the task. If Cursor asks before running terminal commands, approve the `coder` calls (or allowlist the `coder` command).
+- One coder per focused goal. When the work splits into independent parts, decompose it and dispatch each part as its own `coder task run` call - fan out a wide web of coders running in parallel, not one giant dispatch. Give each coder a self-contained goal with all context - overview, file paths, constraints (read-only, git rules). Run independent tasks concurrently; use `steer` to continue a single coder's thread.
+- Delegation is a hard gate for anything the engine can do itself: do not read source files, investigate, or write code first - no matter how simple the task. Fold into the task text whatever only you have - conversation context, results from tools the engine lacks. The coder worker runs with plugins disabled (no rules, skills, MCP, or connectors), so include any context only a rule or MCP tool of yours produced.
+- Compose one self-contained task text (goal, relevant paths, constraints) and dispatch it. It backgrounds by default: the runtime does a startup check and prints a task id (or errors / hands off, see exit codes):
+
+  ```bash
+  coder task run "<task text>"
+  ```
+
+  Fetch the answer with `coder task result <task-id> --wait` - it blocks until the task finishes, then prints only the final result (keeps your context clean). Only use `--wait` when you can run it in a **background terminal** (so it does not block you); if you can't, poll `coder task result <task-id>` (no `--wait`) until it is done. Or skip the two steps and block on the run itself with `--wait` on `coder task run`.
+
+- A `--wait` (on `run` or `result`) exits **4** when the task is waiting on a permission approval: relay the approval to the user, apply their decision with `coder approve <task-id> <approval-id> [--deny]`, then re-fetch with `coder task result <task-id> --wait`. (Unanswered approvals auto-deny after 120s and the task moves on.)
+
+- `coder task run` exits after its startup check. Exit 0: the task started - relay the task id and fetch its result (above). Exit 1: it failed to start or the turn failed - report it, do not retry or fall back yourself. Exit 3: no engine in the chain could start and stdout carries a `run-native-subagent` payload - see below.
+- When the first engine can't start (auth, quota, rate limit), the runtime automatically falls back to the next engine in the chain, runs the same task on it, and still exits 0 - so just fetch the result. If the failure mentions a usage-limit reset time, relay that to the user.
+- Engine, model, and effort come from config; add `--agent` / `--model` / `--effort` when the user asks or it is unambiguous from context (agents: `codex`, `claude`; codex models: `spark`, `luna`, `terra`, `sol`; claude models: `opus`, `sonnet`, `fable`; efforts: `low|medium|high`).
+  - `spark` is only for the very lightest tasks (formatting, renames, quick lookups) - very fast and very cheap. It runs on a separate quota, so reach for it when the others hit a usage limit; it may still run once they are exhausted.
+- Permissions default to auto mode (workspace-write + policy-answered escalations). Pass `--permissions read-only` when the task is read-only; `--permissions workspace-write` to forbid any escalation beyond the project.
+- A background dispatch prints a task id plus its result/steer/stop commands. Relay them and fetch the result (above) rather than polling.
+
+## Last resort: run-native-subagent payload (exit 3)
+
+When no coder engine can start (missing binaries, auth, quota across the whole chain), the runtime exits 3 with a JSON payload (`fallback.action: "run-native-subagent"`). Mention the failure to the user (including any limit-reset time), then run the task with your own subagent facility: spawn one subagent whose prompt is the payload's `task` verbatim, prefixed with: "NEVER run git write operations (commit, checkout, stash, reset, push, etc.); leave changes uncommitted." If the payload's `permissions` is not `auto`, append it: `read-only` means investigate and report without modifying anything; `workspace-write` means never touch anything outside the workspace. Relay its output when it completes.
+
+## Supervision loop
+
+With coders running in the background, don't fire-and-forget: run a recurring monitoring loop in this session (interval by the work's pace, 10m default). Each tick: `coder task list`, fetch finished results, dispatch newly unblocked coders, steer stuck ones, stop off-track ones, surface pending approvals. Stop the loop when all tasks are done and relayed.
+
+## Controlling tasks
+
+- Continue prior work ("keep going", "apply the top fix"): `coder task steer <task-id> "<follow-up>"`.
+- Inspect: `coder task result <task-id>` (status + answer; add `--wait` to block until done) and `coder task list`. (`coder task stream <task-id>` streams the live progress log - to watch/debug in special cases, generally not for you to consume.)
+- Interrupt: `coder task stop <task-id>`.
+- If status shows `pendingApprovals`, surface them to the user; apply their decision with `coder task approve <task-id> <approval-id> [--deny]`.
+
+## Hard rules
+
+- Forward task text verbatim in `steer` follow-ups - never rewrite or summarize what the user asked for.
+- Tell every coder to never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.) and to leave changes uncommitted.
+- Pass the user's constraints (read-only, scoped paths) into each coder's task text, and honor them over your own preferences.

package/.agents/plugins/marketplace.json

@@ -1,18 +0,0 @@
-{
-  "name": "coder-plugins",
-  "interface": {
-    "displayName": "Coder"
-  },
-  "plugins": [
-    {
-      "name": "coder",
-      "source": {
-        "source": "local",
-        "path": "./plugins/codex"
-      },
-      "policy": {
-        "installation": "AVAILABLE"
-      }
-    }
-  ]
-}

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,9 +0,0 @@
-{
-  "name": "coder",
-  "version": "0.2.0",
-  "interface": {
-    "displayName": "Coder (plugin)"
-  },
-  "description": "Delegate coding tasks to a Coder subagent. Your main context stays clean.",
-  "skills": "./skills/"
-}

package/plugins/codex/skills/handle/SKILL.md

@@ -1,51 +0,0 @@
----
-name: handle
-description: Use Coder for any coding, implementation, or investigation task - features, fixes, refactors, debugging, tests, code questions. You orchestrate, never implement yourself; dispatch through the `coder` CLI, one coder per focused goal, fanning out many coders in parallel as the work needs.
----
-
-# Coder dispatch (codex host)
-
-You dispatch coding tasks through the `coder` runtime instead of implementing them yourself. By default the runtime picks the engine from its configured chain; `--agent`/`--model`/`--effort` override it. You never spawn agents yourself in this host.
-
-If `coder` is not on PATH, install it yourself without asking: `npm install -g @wular/coder`, then `coder setup-host codex`. Only if that fails, show the user the error and those two commands. The configured chain (`coder config`) decides which engine runs first and which is the fallback; set it with `coder config set chain <first>,<second>`. Each engine needs its own CLI; the claude engine needs the claude CLI installed - if it is not, ask the user before installing it (on yes: `npm install -g @anthropic-ai/claude-code`, then have them run `claude` once to log in).
-
-When you run setup, also check codex is new enough for the default GPT-5.6 model, which needs codex `>= 0.144` (`codex --version`). If it is older, update it automatically without asking with `codex update` (codex's own updater; fall back to `npm install -g @openai/codex@latest` if it fails), then tell the user to restart their codex session so the update takes effect.
-
-## Dispatching a task
-
-- Run every `coder` command with escalated permissions (outside your sandbox), justification: Coder is a supervisor - it spawns engines, keeps state in `~/.coder`, and enforces its own sandbox and approval policy on the task. Never retry a sandbox-blocked `coder` call sandboxed again or with HOME/state env workarounds.
-- One coder per focused goal. When the work splits into independent parts, decompose it and dispatch each part as its own `coder task run` call - fan out a wide web of coders, not one giant dispatch. Give each coder a self-contained goal with all context - overview, file paths, constraints (read-only, git rules); use `steer` to continue a single coder's thread.
-- Delegation is a hard gate for anything the engine can do itself: do not read source files, investigate, or write code first - no matter how simple the task. Fold into the task text whatever only you have - conversation context, results from tools the engine lacks. The coder worker runs with plugins disabled (no skills, MCP, or connectors), so include any context only a plugin or MCP tool of yours produced.
-- Compose one self-contained task text (goal, relevant paths, constraints) and dispatch it. It backgrounds by default: the runtime does a startup check and prints a task id (or errors / hands off, see exit codes):
-
-  ```bash
-  coder task run "<task text>"
-  ```
-
-  Fetch the answer with `coder task result <task-id> --wait` - it blocks until the task finishes, then prints only the final result (keeps your context clean). Only use `--wait` when you can run it in a **background shell** (so it does not block you); if you can't use that, poll `coder task result <task-id>` (no `--wait`) until it is done. Or skip the two steps and block on the run itself with `--wait` on `coder task run`. A `--wait` exits **4** when the task is waiting on a permission approval: relay it to the user, apply their decision with `coder approve <task-id> <approval-id> [--deny]`, then re-fetch with `coder task result <task-id> --wait` (unanswered approvals auto-deny after 120s and the task moves on).
-
-- `coder task run` exits after its startup check. Exit 0: the task started - fetch its result (above). Exit 1: it failed to start / the turn failed - report it, do not retry.
-- Exit 3: no engine in the chain could start; stdout carries a JSON payload (`fallback.action: "run-native-subagent"`). Mention the failure to the user (including any limit-reset time), then run the task with your own subagent facility: spawn one subagent whose prompt is the payload's `task` verbatim, prefixed with: "NEVER run git write operations (commit, checkout, stash, reset, push, etc.); leave changes uncommitted." If the payload's `permissions` is not `auto`, append it: `read-only` means investigate and report without modifying anything; `workspace-write` means never touch anything outside the workspace. Relay its output when it completes.
-- When the first engine can't start (auth, quota, rate limit), the runtime automatically falls back to the next engine in the chain, runs the same task on it via CLI, and still exits 0 - so just fetch the result. If the failure mentions a usage-limit reset time, relay that to the user.
-
-- Engine, model, and effort come from config; add `--agent` / `--model` / `--effort` when the user asks or it is unambiguous from context (agents: `codex`, `claude`; codex models: `spark`, `luna`, `terra`, `sol`; claude models: `opus`, `sonnet`, `fable`; efforts: `low|medium|high`).
-  - `spark` is only for the very lightest tasks (formatting, renames, quick lookups) - very fast and very cheap. It runs on a separate quota, so reach for it when the others hit a usage limit; it may still run once they are exhausted.
-- Permissions default to auto mode. Pass `--permissions read-only` when the task is read-only; `--permissions workspace-write` to forbid any escalation beyond the project.
-- A background dispatch prints a task id plus its result/steer/stop commands. Relay them and fetch the result (above) rather than polling.
-
-## Supervision loop
-
-With coders running in the background, don't fire-and-forget: run a recurring monitoring loop in this task (interval by the work's pace, 10m default). Each tick: `coder task list`, fetch finished results, dispatch newly unblocked coders, steer stuck ones, stop off-track ones, surface pending approvals. Stop the loop when all tasks are done and relayed.
-
-## Controlling tasks
-
-- Continue prior work ("keep going", "apply the top fix"): `coder task steer <task-id> "<follow-up>"`.
-- Inspect: `coder task result <task-id>` (status + answer; add `--wait` to block until done) and `coder task list`. (`coder task stream <task-id>` streams the live progress log - to watch/debug in special cases, generally not for you to consume.)
-- Interrupt: `coder task stop <task-id>`.
-- If status shows `pendingApprovals`, surface them to the user; apply their decision with `coder task approve <task-id> <approval-id> [--deny]`.
-
-## Hard rules
-
-- Forward task text verbatim in `steer` and retries - never rewrite or summarize what the user asked for.
-- Tell every coder, in its task text, to never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.) and to leave changes uncommitted. The runtime's permission model also enforces this on the engines.
-- Pass the user's constraints (read-only, scoped paths) into each coder's task text, and honor them over your own preferences.

package/plugins/cursor/skills/handle/SKILL.md

@@ -1,50 +0,0 @@
----
-name: handle
-description: Use Coder for any coding, implementation, or investigation task - features, fixes, refactors, debugging, tests, code questions. You orchestrate, never implement yourself; dispatch through the `coder` CLI, one coder per focused goal, fanning out many coders in parallel as the work needs.
----
-
-# Coder dispatch (Cursor host)
-
-You dispatch coding tasks through the `coder` runtime instead of implementing them yourself. By default the runtime picks the engine from its configured chain; `--agent`/`--model`/`--effort` override it. You never spawn agents yourself; the runtime spawns and supervises them.
-
-If `coder` is not on PATH, install it yourself without asking: `npm install -g @wular/coder`, then run `coder setup-host` to seed the config and check engine readiness (no host plugin is installed - Cursor gets this skill from the marketplace). Only if that fails, show the user the error and those commands. Coder needs at least one engine CLI installed and logged in: codex (`npm install -g @openai/codex`, then `codex login`) and/or claude (`npm install -g @anthropic-ai/claude-code`, then run `claude` once to log in) - ask the user before installing an engine CLI. The configured chain (`coder config`) decides which engine runs first and which is the fallback; set it with `coder config set chain <first>,<second>`.
-
-When you run setup, also check codex is new enough for the default GPT-5.6 model, which needs codex `>= 0.144` (`codex --version`). If it is older, update it automatically without asking with `codex update` (codex's own updater; fall back to `npm install -g @openai/codex@latest` if it fails), then tell the user to restart their codex session so the update takes effect.
-
-## Dispatching a task
-
-- `coder` commands are safe to run in the terminal - the runtime is a supervisor: it spawns engines, keeps state in `~/.coder`, and enforces its own OS sandbox and approval policy on the task. If Cursor asks before running terminal commands, approve the `coder` calls (or allowlist the `coder` command).
-- One coder per focused goal. When the work splits into independent parts, decompose it and dispatch each part as its own `coder task run` call - fan out a wide web of coders, not one giant dispatch. Give each coder a self-contained goal with all context - overview, file paths, constraints (read-only, git rules); use `steer` to continue a single coder's thread.
-- Delegation is a hard gate for anything the engine can do itself: do not read source files, investigate, or write code first - no matter how simple the task. Fold into the task text whatever only you have - conversation context, results from tools the engine lacks. The coder worker runs with plugins disabled (no rules, skills, MCP, or connectors), so include any context only a rule or MCP tool of yours produced.
-- Compose one self-contained task text (goal, relevant paths, constraints) and dispatch it. It backgrounds by default: the runtime does a startup check and prints a task id (or errors, see exit codes):
-
-  ```bash
-  coder task run "<task text>"
-  ```
-
-  Fetch the answer with `coder task result <task-id> --wait` - it blocks until the task finishes, then prints only the final result (keeps your context clean). Run it in a **background terminal** so it does not block you; if you can't, poll `coder task result <task-id>` (no `--wait`) until it is done. Or skip the two steps and block on the run itself with `--wait` on `coder task run`. A `--wait` exits **4** when the task is waiting on a permission approval: relay it to the user, apply their decision with `coder task approve <task-id> <approval-id> [--deny]`, then re-fetch with `coder task result <task-id> --wait` (unanswered approvals auto-deny after 120s and the task moves on).
-
-- `coder task run` exits after its startup check. Exit 0: the task started - fetch its result (above). Exit 1: it failed to start / the turn failed - report it, do not retry.
-- Exit 3: no engine in the chain could start; stdout carries a JSON payload (`fallback.action: "run-native-subagent"`). Mention the failure to the user (including any limit-reset time), then run the task with your own subagent facility: spawn one subagent whose prompt is the payload's `task` verbatim, prefixed with: "NEVER run git write operations (commit, checkout, stash, reset, push, etc.); leave changes uncommitted." If the payload's `permissions` is not `auto`, append it: `read-only` means investigate and report without modifying anything; `workspace-write` means never touch anything outside the workspace. Relay its output when it completes.
-- Codex startup failures (auth, quota, rate limit) fall back to the next engine in the chain automatically - the runtime reruns the same task on the claude engine via its CLI and still exits 0, so just fetch the result. If it mentions a usage-limit reset time, relay that to the user.
-- Engine, model, and effort come from config; add `--agent` / `--model` / `--effort` when the user asks or it is unambiguous from context (agents: `codex`, `claude`; codex models: `spark`, `luna`, `terra`, `sol`; claude models: `opus`, `sonnet`, `fable`; efforts: `low|medium|high`).
-  - `spark` is only for the very lightest tasks (formatting, renames, quick lookups) - very fast and very cheap. It runs on a separate quota, so reach for it when the others hit a usage limit; it may still run once they are exhausted.
-- Permissions default to auto mode. Pass `--permissions read-only` when the task is read-only; `--permissions workspace-write` to forbid any escalation beyond the project.
-- A background dispatch prints a task id plus its result/steer/stop commands. Relay them and fetch the result (above) rather than polling.
-
-## Supervision loop
-
-With coders running in the background, don't fire-and-forget: run a recurring monitoring loop in this session (interval by the work's pace, 10m default). Each tick: `coder task list`, fetch finished results, dispatch newly unblocked coders, steer stuck ones, stop off-track ones, surface pending approvals. Stop the loop when all tasks are done and relayed.
-
-## Controlling tasks
-
-- Continue prior work ("keep going", "apply the top fix"): `coder task steer <task-id> "<follow-up>"`.
-- Inspect: `coder task result <task-id>` (status + answer; add `--wait` to block until done) and `coder task list`. (`coder task stream <task-id>` streams the live progress log - to watch/debug in special cases, generally not for you to consume.)
-- Interrupt: `coder task stop <task-id>`.
-- If status shows `pendingApprovals`, surface them to the user; apply their decision with `coder task approve <task-id> <approval-id> [--deny]`.
-
-## Hard rules
-
-- Forward task text verbatim in `steer` and retries - never rewrite or summarize what the user asked for.
-- Tell every coder, in its task text, to never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.) and to leave changes uncommitted. The runtime's permission model also enforces this on the engines.
-- Pass the user's constraints (read-only, scoped paths) into each coder's task text, and honor them over your own preferences.