Homeboy
Changelog
All notable changes to Homeboy CLI are documented in this file. (This file is embedded into the CLI binary and...
Configuration Reference
This page is a field-level reference for Homeboy configuration structures. For the higher-level system model and core/extension boundary, see Architecture...
Homeboy CLI documentation
This directory contains the markdown docs embedded into the homeboy binary and displayed via homeboy docs. Homeboy is headless automation...
Cross-Compilation Guide
Homeboy can orchestrate releases for any platform, but building native binaries requires access to that platform's toolchain. What Works Anywhere...
Code Factory
The code factory is homeboy's model for automated code maintenance: humans write features, the system maintains quality. It combines lint,...
Template Variables
Homeboy supports template variables in several contexts. Both single-brace ({var}) and double-brace ({{var}}) syntaxes are supported everywhere for backward compatibility....
`homeboy self`
Inspect the active Homeboy binary and nearby install/update signals. Synopsis homeboy self <COMMAND> Subcommands status — report the active binary,...
Fuzz Command
List and run generic fuzz workloads for a Homeboy component or rig. Synopsis homeboy fuzz [<component>] [--rig <id>] [--workload <id>]...
Rig Spec Reference
JSON reference for rig specs loaded from ~/.config/homeboy/rigs/<id>.json or installed from a rig package. Package Layout A rig package can...
`homeboy runner`
Synopsis homeboy runner <COMMAND> runner manages durable execution backends. SSH runners are a capability on a homeboy server record, so...
homeboy trace
Capture black-box behavioral traces for a component by executing declared scenarios. Trace runners write a JSON evidence envelope plus optional...
`homeboy wp`
Run WP-CLI commands through an extension-provided top-level CLI verb. Synopsis homeboy wp <project_id> [args]... For multisite projects, use project:subtarget as...
Project Schema
Project configuration defines environment-specific context stored in projects/<id>.json: server bindings, domains, local paths, remote paths, project-scoped CLI settings, API settings,...
Portable Component Config (`homeboy.json`)
A homeboy.json file in a repo root defines portable component configuration that travels with the code. Clone a repo, run...
Extension Manifest Schema
Extension manifests define extension metadata, runtime behavior, platform behaviors, and integration points. Stored as <extension_id>/<extension_id>.json in the extension directory. Schema...
Component Schema
Component configuration defines buildable and deployable units stored in components/<id>.json. Schema { "id": "string", "name": "string", "local_path": "string", "remote_path": "string",...
Fleet Schema
Fleet configuration defines named groups of projects stored in fleets/<id>.json. Schema { "id": "string", "project_ids": ["string"], "description": "string" } Fields...
Server Schema
Server configuration defines SSH server connections stored in servers/<id>.json. Schema { "id": "string", "name": "string", "host": "string", "port": number, "user":...
Provider fanout boundary
Homeboy core owns durable orchestration and provider-neutral evidence. Runtime providers own backend-specific execution details. The seam is the AgentTaskRequest/AgentTaskOutcome adapter...
JSON output contract
Homeboy prints JSON to stdout for most commands. Exceptions: homeboy docs prints raw markdown (or newline-delimited topic names for homeboy...
Lifecycle Contracts
Homeboy defines a product-neutral lifecycle contract for workloads that mutate state and need fuzz-safe cleanup. Core owns the vocabulary and...
Runner contract
The contract between Homeboy core and runner scripts: what capabilities exist, what env vars flow in, what sidecar files scripts...
CI result JSON contract
Homeboy CI results are exposed through the existing global --output <path> flag. The flag writes the same JSON envelope Homeboy...
Planned Change Execution
Homeboy's planned-change vocabulary is the shared core language for work that starts as a plan and may eventually mutate files...
Architecture Cleanup Map
This map tracks lower-risk source-boundary cleanup. It is intentionally scoped to developer guidance and ratchets; command implementation refactors should happen...
Architecture Overview
Homeboy is headless automation for agentic software engineering workflows. It is built in Rust with a config-driven, extension-oriented architecture that...
Config Directory Structure
Important: Portable component configuration can live in a repo-level homeboy.json. Reusable machine-local configuration, state, installed extensions, projects, servers, fleets, rigs,...
Error Handling Patterns
Homeboy uses a centralized error system for consistent error reporting across all commands. Error Categories Errors are categorized by type...
Release-gate proof: the canonical non-local command path
This is the one documented command path agents should use to produce release-gate proof from a worktree. It uses normal...
Controller to runner reverse-runner setup
This guide is the operator runbook for using any Homeboy-managed controller machine as a broker while any configured runner machine...
`homeboy` root command
Synopsis homeboy [OPTIONS] <COMMAND> Description homeboy is headless automation for agentic software engineering workflows. It keeps local developers, CI, scheduled...
Verification phase contract
Homeboy's verification surface is deliberately split into isolated primitive commands that can be composed by higher-level workflows. Primitive phases The...
Compiler Warning Extension Contract Gap
Issue #2242 asks Homeboy core to move compiler-warning collection and compiler-warning fix generation behind extension-owned contracts. Validation and formatting already...
Dead Guard Detection
Homeboy audit flags function_exists('…'), class_exists('…'), and defined('…') guards whose checked symbol is guaranteed to exist at runtime. Such guards are...
Repeated literal-shape detector
Detects inline associative array literals that appear many times with the same shape (ordered keys + value kinds) across a...
Shared scaffolding detector
Finds groups of classes in the same directory subtree that share the same overall method-shape (same method names, visibilities, and...
Audit Deprecation Age
Homeboy audit flags @deprecated X.Y.Z docblock tags that are significantly older than the component's current version. This surfaces ancient deprecations...
Documentation Alignment
Instructions for keeping existing .md documentation synchronized with current codebase implementation. Scope Alignment covers documentation that describes current implementation only....
Documentation Structure
Standard patterns for organizing documentation files and directories. Directory Conventions /docs Directory User-facing documentation lives in /docs at the project...
Documentation Generation
Instructions for creating comprehensive user-facing documentation from scratch by analyzing the codebase. Purpose Generate structured documentation in the /docs directory...
Documentation Management
Homeboy provides AI agents with consistent instructions for documentation generation and maintenance. These docs serve as the single source of...