Skip to content

feat(agents-md): contribute homeboy CLI section when on PATH#56

Merged
chubes4 merged 1 commit into
mainfrom
feat/homeboy-section
Apr 25, 2026
Merged

feat(agents-md): contribute homeboy CLI section when on PATH#56
chubes4 merged 1 commit into
mainfrom
feat/homeboy-section

Conversation

@chubes4
Copy link
Copy Markdown
Member

@chubes4 chubes4 commented Apr 25, 2026

Summary

When the homeboy Rust CLI is on PATH, AGENTS.md gains a ## Homeboy section that maps the verbs agents reach for and the repo-level rules they must respect.

Adds:

  • inc/Homeboy.php — capability helper. Single command -v homeboy probe, memoized, hard-gated on Environment::has_shell().
  • SectionRegistry contributor at priority 35 (between wordpress-source and multisite).
  • tests/smoke-homeboy.php — 5 assertions across no-shell / empty-PATH / synthetic-on-PATH / memoization / reset_cache.

Design

Sits on top of #57 (DMC = WP↔runtime bridge). Mirrors the house style of ## Data Machine and ## Abilities: terse map, bold sub-labels, one discoverability hint at the end. The CLI is its own source of truth — homeboy --help enumerates everything; this section calls out the verbs agents should reach for and the repo rules that protect release automation.

Section content (preview)

## Homeboy

`homeboy` is a Rust CLI on this host. Every verb runs the same locally as in CI.

**Quality:** `homeboy audit | lint | test | refactor`

**Git:** prefer `homeboy git changes | status | commit | push | pull | tag`
— auto-baselines, structured output, `--json` bulk. One-off reads
(`git diff`, `git show`, `git blame`) stay on raw `git`.

**Perf + envs:** `homeboy bench` for pinned benchmarks, `homeboy rig` for
reproducible dev environments.

**Repo rules** (when `homeboy.json` is present):
- **NEVER edit `CHANGELOG.md`** — generated from conventional commits at
  release time.
- **NEVER hand-bump version strings** — `feat:`/`fix:`/`BREAKING CHANGE`
  drive semver; Homeboy rewrites version targets in `homeboy.json`.

Run `homeboy --help` for the full verb list. Operator verbs
(`release`, `deploy`, `fleet`, `ssh`) only on explicit ask.

Tests

$ php tests/smoke-homeboy.php
✓ empty PATH: is_available() returns false
✓ absent: result is memoized
✓ synthetic on PATH: is_available() returns true
✓ memoization: result sticky after PATH change
✓ reset_cache: re-probe sees current state
OK

Pure-PHP, no WP bootstrap. Deterministic via PATH override.

AI assistance

  • AI assistance: Yes
  • Tool(s): Claude Code (Sonnet 4.5)
  • Used for: Drafted helper, contributor, smoke, and this body. Iterated section content twice — first draft over-enumerated verbs (mentioned release, deploy, fleet as primary; missed bench and rig); second draft over-explained ("prefer-over-raw-git" essay paragraphs). Chris pushed back on both ("you overcorrected"; "match the house style — minimal, clean map") and the section was tightened to mirror ## Data Machine density.

@chubes4 chubes4 force-pushed the feat/homeboy-section branch from 062cb0c to 5d20678 Compare April 25, 2026 13:36
@chubes4 chubes4 changed the title feat(agents-md): contribute homeboy section on homeboy-managed installs feat(agents-md): contribute homeboy CLI section when on PATH Apr 25, 2026
@chubes4 chubes4 force-pushed the feat/homeboy-section branch 2 times, most recently from 753aaee to ba2fb41 Compare April 25, 2026 14:10
Adds optional Homeboy awareness to data-machine-code. When the
`homeboy` Rust CLI (https://github.com/Extra-Chill/homeboy) is callable
from this host's shell, AGENTS.md gains a `## Homeboy` section that
teaches agents the verb surface and the release-automation rules they
must respect inside Homeboy-managed repos.

Why this lives here: data-machine-code is the bridge between WordPress
and an external coding-agent runtime. Surfacing extra CLI tools the
runtime can call (`homeboy`, on top of `git`, `wp-cli`, etc.) is
exactly the kind of thing that belongs in the bridge layer. Homeboy
itself stays PHP-free.

What the section teaches agents (only when `homeboy` is on PATH):
- The verb surface — `audit`, `lint`, `test`, `git <verb>`, `deploy`,
  `component list`, `release` — with `homeboy --help` as the canonical
  source of truth for the full list.
- Release-automation rules for any repo with a `homeboy.json`:
  - NEVER edit `CHANGELOG.md` — Homeboy generates it from conventional
    commits at release time.
  - NEVER hand-bump version strings — Homeboy rewrites version targets
    declared in `homeboy.json` automatically from `feat:` / `fix:` /
    `BREAKING CHANGE` commits.
  - Use conventional commits; `feat:` / `fix:` trigger releases.

Mirrors how DMC's existing `## Abilities` section works: teach the
discovery primitive (`homeboy --help`), trust the CLI to be its own
source of truth. Don't enumerate state in AGENTS.md that the tool can
list itself.

`DataMachineCode\Homeboy` mirrors the shape of `Environment`:
- `is_available()` — single shell probe via `command -v homeboy`,
  memoized for the request lifecycle.
- `reset_cache()` — test-only seam.

Hard-gated on `Environment::has_shell()` so hosts with `shell_exec`
disabled get a graceful false, never a fatal.

Tests: tests/smoke-homeboy.php — 5 assertions on the probe across
no-shell / empty-PATH / synthetic-on-PATH / memoization / reset_cache
branches. Pure-PHP, no WP bootstrap, deterministic via PATH override.
@chubes4 chubes4 force-pushed the feat/homeboy-section branch from ba2fb41 to eeac395 Compare April 25, 2026 14:11
@chubes4 chubes4 merged commit 6c124a7 into main Apr 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant