Homeboy Extensions

Official extension directory for Homeboy. Each extension is a project-type primitive — it teaches Homeboy how to discover, audit, lint, test, and release a particular kind of codebase.

This is a monorepo — each subdirectory is a standalone extension. Install individual extensions, not the whole repo.

Agent runtimes live under agent-runtimes/. The WP Codebox runtime is exposed at agent-runtimes/wp-codebox as a first-class runtime package; project extensions can depend on runtime capabilities without embedding the provider contract.

Generic runtime package requirements are documented in docs/agent-runtime-package-contract.md. Use tests/fixtures/agent-runtime-manifest.json for static contract assertions; agent-runtimes/ contains only shipped runtime packages.

Generic project-root, package-manager, and named-script execution helpers live in scripts/lib/project-scripts.sh and are documented in docs/project-script-runtime.md. They are extension-owned until Homeboy core grows an ecosystem-neutral runtime helper contract.

Generic runtime loop, fanout/reconcile, proof, and lifecycle primitives are exported from homeboy-runtime-agent-ci/generic-orchestration; provider and workflow adapters are exported from homeboy-runtime-agent-ci/provider-adapters. Module internals live in runtime-agent-ci/lib/ and are documented in docs/generic-fanout-reconcile-workflow.md.

Declarative dependency adapter manifests live in dependency-adapters/. They describe extension-owned Node.js, Composer, and WordPress dependency materialization surfaces without teaching Homeboy core ecosystem-specific package-manager behavior. Use .github/workflows/runtime-agent-full-run.yml for the standard single-task path: injectable runtime execution, workspace verification, dry-run or PR publication evidence, and one final green/red proof envelope.

Integration-specific examples live under docs/integrations/ when a reusable integration needs documentation outside its owning project.

Available Extensions

Extension	Description
wordpress	WordPress project type — WP-CLI, build, test (via Playground), and lint (PHPCS + WPCS + PHPStan + ESLint)
rust	Rust project type — Cargo CLI, fingerprint/refactor, test/lint runners, crates.io and Homebrew publish
nodejs	Node.js project type — discovery, audit grammar (Express/Mongoose/etc.), and npm release lifecycle
go	Go project type — Cargo-equivalent CLI integration for services and binaries
swift	Swift project type — testing infrastructure for macOS, iOS, and Swift CLI projects
managed-preview	Provider command helpers for Homeboy managed service public previews

Scope

These extensions cover the codebase lifecycle: discover, audit, lint, test, refactor, release, deploy. Anything that runs as a long-lived process, talks to a remote API at runtime, or scrapes/automates external services belongs in Sweatpants, not here.

GitHub Releases are handled by Homeboy core. Rust binary archives and Homebrew formulae are generated by cargo-dist, then the Rust extension's release.publish action publishes crates.io and Homebrew tap updates through the standard Homeboy release pipeline.

Installation

Install extensions one at a time. Homeboy clones this repo, detects the monorepo layout, and extracts just the extension you asked for into ~/.config/homeboy/extensions/<id>/.

homeboy extension install https://github.com/Extra-Chill/homeboy-extensions --id wordpress
homeboy extension install https://github.com/Extra-Chill/homeboy-extensions --id rust
homeboy extension install https://github.com/Extra-Chill/homeboy-extensions --id nodejs

Remote runners need the same extension IDs installed on the runner host before Homeboy can offload matching jobs to them. For the standard runner bootstrap path, see docs/remote-runner-bootstrap.md.

Verify installation

# List all installed extensions
homeboy extension list

# Inspect a specific extension
homeboy extension show wordpress

Install from a local clone

Local path installs are for active extension development:

git clone https://github.com/Extra-Chill/homeboy-extensions.git
homeboy extension install ./homeboy-extensions/wordpress
homeboy extension install ./homeboy-extensions/rust

Install modes and updates

For normal use, install from the GitHub monorepo URL with --id <extension>. Homeboy manages the cloned/extracted install and can update that installed copy:

homeboy extension install https://github.com/Extra-Chill/homeboy-extensions --id wordpress

Local path installs are linked installs. The active extension code is whatever the installed symlink target points at, so updating the primary homeboy-extensions checkout does not update an extension linked to another checkout or feature worktree. Avoid linking installed extensions to short-lived worktrees unless you are intentionally testing that branch.

To repair a runner that was accidentally left linked to a stale or dirty checkout, use the standard bootstrap script with --replace-existing. For linked installs, Homeboy removes only the installed symlink, preserves the linked checkout, and installs a managed extracted copy from the configured repository URL:

scripts/bootstrap-standard-extensions.sh --target example-runner --extensions "wordpress" --replace-existing

Inspect the current state before debugging extension behavior:

homeboy extension list
homeboy extension show wordpress
readlink ~/.config/homeboy/extensions/wordpress

To reset a stale linked install, uninstall and reinstall from the GitHub URL, or relink intentionally to the checkout you want active.

Usage

Once installed, declare the extension in your repo's homeboy.json and Homeboy will pick it up automatically:

{
  "id": "my-project",
  "extensions": {
    "wordpress": {}
  }
}

Then run Homeboy commands as usual:

homeboy audit
homeboy lint --fix
homeboy test
homeboy release

Runtime agent full-run tasks

The reusable .github/workflows/runtime-agent-full-run.yml workflow is a thin GitHub Actions adapter over the headless deterministic loop runner in runtime-agent-ci. Use runtime_task or the ability_request/ability_input shorthand for direct ability execution. Mount downloaded GitHub Actions artifacts with runtime_mounts, and enforce typed outputs with artifact_declarations plus runtime_output_projections.

Callers select runtimes with runtime and profile. Omitting runtime selects the neutral local-shell runtime for generic contract smokes; WordPress callers must pass runtime: wp-codebox explicitly.

Call .github/workflows/runtime-agent-full-run.yml directly for runtime-backed agent runs. WP Codebox callers use the same workflow with runtime: wp-codebox and canonical selected-runtime inputs such as runtime_mounts, runtime_overlays, runtime_profiles, component_contracts, and artifact_declarations. See .github/workflows/README.md for workflow inputs and integration examples.

Use component_contracts only when the ability provider plugin or runtime component must be mounted explicitly. Keep ability names, schemas, and artifact types owned by the caller; Homeboy Extensions only forwards the generic runtime task contract.

Non-GitHub callers can run the same primitive directly:

node runtime-agent-ci/scripts/run-headless-loop.cjs \
  --spec runtime-agent-full-run-config.json \
  --result loop-result.json \
  --events loop-events.json \
  --outcome agent-task-outcome.json \
  --results run-results.json

The CLI accepts the same loop spec/config that GitHub Actions materializes, plus an injected runtime_manifest when the caller does not want to rely on the checked-in runtime registry. It emits durable JSON loop results, ordered events, and the existing outcome/results files consumed by workflow adapters.

The public runtime-agent-ci binaries are the package bin entries. The package exposes only explicit subpath exports for public surfaces.

WP Codebox is expected to consume a wp-codebox/runtime-profile/v1 payload with generic runtime dependencies such as components, plugins, mu_plugins, themes, overlays, runtime_overlays, env, and provider_plugins. Homeboy Extensions forwards those shapes as Codebox-owned runtime profile data through the current public runtime profile contract. Sandbox tool selection and other substrate details remain WP Codebox-owned; Homeboy task schemas and caller-owned artifact declarations are prepared by Homeboy Extensions before WP Codebox runs the task.

Codebox contract discovery is limited to public package exports or an explicit HOMEBOY_WP_CODEBOX_CORE_MODULE supplied by the runner. Homeboy Extensions does not probe WP Codebox cache/source package layouts for private files.

Homeboy Extensions consumes a Codebox-owned wp-codebox/parent-tool-bridge/v1 when the runtime profile exposes one. When it is missing, the adapter declares the upstream primitive requirement in the runtime profile for WP Codebox to fulfill through the public parent-tool-bridge contract.

For WordPress fuzzing, Homeboy Extensions builds and forwards the Codebox-owned wp-codebox/fuzz-suite/v1 request through the WP Codebox runtime task boundary. HBX may describe WordPress targets, seeds, limits, coverage requests, and artifact expectations, but WP Codebox owns the fuzz execution loop and result envelope.

Caller workflows should use core homeboy fuzz plan to compose the Homeboy-level fuzz execution request. HBX does not own homeboy fuzz ... command assembly; it only contributes WordPress-specific contracts that the core planner and WP Codebox runtime consume.

Each extension also exposes a CLI binding for direct use against a project or component:

# WordPress
homeboy wp my-site plugin list

# Rust
homeboy cargo my-crate build

Creating Extensions

Each extension is a directory containing a <extension-id>.json manifest. The manifest defines capabilities, audit grammar, release actions, and CLI bindings. See wordpress/wordpress.json and rust/rust.json for full examples.

Each extension owns its own CHANGELOG.md at <extension>/docs/CHANGELOG.md, generated by Homeboy at release time. There is no monorepo-level changelog — extensions release independently.