Workers for the iii engine. Each top-level directory is a self-contained worker module: a process that connects to the engine over WebSocket, registers functions + triggers, and does something useful.

Workers are installed via iii worker add <name>, which resolves the matching asset for the host from the workers registry API.

Each worker ships an agent skill under <worker>/skills/. Install them with the skills CLI (works with Claude Code, Cursor, and 30+ other agents).

# List every worker skill in this repo
npx skills add iii-hq/workers --list

# Install one worker's skill
npx skills add iii-hq/workers --skill database

# Install several
npx skills add iii-hq/workers --skill database,coder,shell

# Install all worker skills at once
npx skills add iii-hq/workers --all

For the iii engine's top-level skills (mental model, SDKs, config, patterns), see iii-hq/iii:

npx skills add iii-hq/iii --all

Workers target the iii-sdk package on each ecosystem:

• Rust — crates.io/crates/iii-sdk
• Node — npmjs.com/package/iii-sdk
• Python — pypi.org/project/iii-sdk

Each module pins its exact version in its own manifest (Cargo.toml, package.json, or pyproject.toml).

Rust workers:

cd <worker>
cargo build --release

Node/Python workers follow the standard npm install / pip install -e . flow — see each module's README for specifics. harness is a pnpm monorepo (pnpm install && pnpm build).

Rust workers ship as standalone binaries — see the modules table above — and are released via GitHub Actions:

1. Trigger the Create Tag workflow (Actions tab) — pick a worker, bump type (patch/minor/major), and a registry tag (latest / next).
2. A tag of the form <worker>/v<X.Y.Z> is pushed to main, with the registry tag embedded in the tag's annotated message.
3. The unified Release workflow fires on the tag, cross-compiles binaries for up to 9 targets (Linux gnu/musl, macOS x86_64 + aarch64, Windows x86_64/i686/aarch64, armv7), uploads them to a GitHub Release with SHA-256 checksums, and calls POST /publish on the workers registry API.

Targets per build (Windows targets are skipped on POSIX-only workers such as shell):

aarch64-apple-darwin
x86_64-apple-darwin
x86_64-pc-windows-msvc
i686-pc-windows-msvc
aarch64-pc-windows-msvc
x86_64-unknown-linux-gnu
x86_64-unknown-linux-musl
aarch64-unknown-linux-gnu
armv7-unknown-linux-gnueabihf

Workers are discovered through the workers registry API at https://api.workers.iii.dev. Each release publishes a manifest entry declaring the worker kind (binary / container image), supported targets, download URLs, and the worker's collected function + trigger interface. iii worker add <name> queries this API to locate the right asset for the host.

Start with docs/sops/new-worker.md — the cross-cutting checklist (naming, required files, CI gates, release wiring). For the inside of a Rust deploy: binary worker, continue with docs/sops/binary-worker.md. Each worker ships a consumer README.md per the worker-readme.md contract (install via iii worker add, quickstart, configuration). docs/README.md indexes all shared docs.

Pull requests trigger per-worker lint + tests for the changed worker(s). .github/workflows/ci.yml discovers changes by reading each worker's iii.worker.yaml, then routes:

• Rust → cargo fmt --check, cargo clippy -- -D warnings, cargo test --all-features
• Node → biome ci against biome.json and npm test
• Python → ruff check + ruff format --check against ruff.toml and pytest

The pr-checks job additionally enforces, per changed worker: README.md present, iii.worker.yaml valid, tests/ non-empty, and the manifest version is greater than the version on the PR's base branch.

Full reference (discovery buckets, interface boot smoke, e2e workflows): docs/architecture/testing-and-ci.md.

Releases are cut manually via the Create Tag workflow (.github/workflows/create-tag.yml) — pick a worker, a bump type, and a registry tag (latest / next). The resulting <worker>/v<X.Y.Z> tag drives a single dispatcher (.github/workflows/release.yml) that:

1. Routes on deploy from iii.worker.yaml:
   • binary → cross-compile via _rust-binary.yml.
   • image → multi-arch image to ghcr.io/<owner>/<worker> via _container.yml.
   • bundle → single-file archive via _bundle.yml.
2. Calls POST /publish against the workers registry API via _publish-registry.yml.

Step-by-step (variants, troubleshooting, rollback): docs/sops/release.md.

Apache 2.0 — see LICENSE.