docs: document optional Homeboy setup (#98)

chubes4 · web-flow · commit fe9c4a48c289 · 2026-05-02T12:06:35.000-04:00
diff --git a/README.md b/README.md
@@ -124,6 +124,7 @@ systemctl start kimaki  # or: systemctl start cc-connect
 | `--existing` | Add to existing WordPress (skip WP install) |
 | `--wp-path <path>` | Path to WordPress root (implies `--existing`) |
 | `--agent-slug <slug>` | Override Data Machine agent slug (default: derived from domain) |
+| `--with-homeboy` | Enable optional [Homeboy](https://github.com/Extra-Chill/homeboy) project setup for repo-aware developer workflows |
 | `--no-chat` | Skip chat bridge |
 | `--chat <bridge>` | Chat bridge: `kimaki` (Discord, default for OpenCode), `cc-connect` (default for Claude Code and Studio Code), `telegram` |
 | `--multisite` | Convert to WordPress Multisite (subdirectory by default) |
@@ -147,6 +148,9 @@ EXISTING_WP=~/Studio/my-site ./setup.sh --local --runtime claude-code
 # Local: Studio Code + DM (auto-detected in Studio sites)
 EXISTING_WP=~/Studio/my-site ./setup.sh --local --runtime studio-code
 
+# Local: recommended developer power layer with Homeboy project setup
+EXISTING_WP=~/Studio/my-site ./setup.sh --local --with-homeboy
+
 # Local: no chat bridge (terminal only)
 EXISTING_WP=~/Studio/my-site ./setup.sh --local --no-chat
 
@@ -177,6 +181,7 @@ SITE_DOMAIN=example.com ./setup.sh --dry-run
 | **[OpenCode](https://opencode.ai)**, **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)**, or **[Studio Code](https://developer.wordpress.com/studio/)** | AI coding agent runtime | Selected via `--runtime` |
 | **[Data Machine](https://github.com/Extra-Chill/data-machine)** | Memory (SOUL/USER/MEMORY.md), self-scheduling, AI tools, Agent Ping | No — wp-coding-agents composes on top of DM |
 | **[Data Machine Code](https://github.com/Extra-Chill/data-machine-code)** | Workspace management, GitHub integration, git operations | Installed with Data Machine |
+| **[Homeboy](https://github.com/Extra-Chill/homeboy)** | Optional developer power layer for project status, component-aware checks, review loops, and WordPress extension verification | `--with-homeboy` |
 | **[Kimaki](https://kimaki.xyz)**, **[cc-connect](https://github.com/nichochar/cc-connect)**, or **[opencode-telegram](https://github.com/grinev/opencode-telegram-bot)** | Chat bridge (Discord, multi-platform, or Telegram) | `--no-chat` |
 | **SessionStart hook** | Syncs Data Machine agents into CLAUDE.md on every session (Claude Code and Studio Code) | Always installed |
 | **[WordPress agent skills](https://github.com/WordPress/agent-skills)** | WP development patterns (cloned at install) | `--no-skills` |
@@ -238,6 +243,51 @@ Data Machine is the substrate wp-coding-agents composes on top of — memory, sc
 - GitHub integration (issues, PRs, repos)
 - Policy-controlled git operations (add, commit, push with allowlists; primary checkout is read-only by default)
 
+## Optional Homeboy Layer
+
+`--with-homeboy` adds Homeboy as an optional, recommended developer power layer. Homeboy is not bundled or vendorized by wp-coding-agents; setup verifies or installs the external Homeboy CLI, verifies the WordPress extension, then exposes its availability to Data Machine Code so composed agent instructions can include Homeboy workflows.
+
+The setup model is intentionally specific:
+
+```text
+WordPress site root
+  = Homeboy project
+
+DMC workspace primary checkouts
+  = Homeboy components attached to that project
+
+DMC worktrees (`repo@branch`)
+  = task-specific ephemeral worktrees skipped by default
+```
+
+The site root is a Homeboy project, not a component, so setup does not create `homeboy.json` in the WordPress root. Primary Data Machine Code workspace checkouts that already contain `homeboy.json` can be attached as project components. Per-branch `@` worktrees are skipped by default because they are temporary task checkouts derived from the primary component repos.
+
+When enabled, setup should leave you with:
+
+- A Homeboy project for the WordPress site, derived from the site ID, domain, and base path
+- Attached Homeboy components for eligible DMC workspace primary checkouts
+- WordPress Homeboy extension installed and verified
+- Data Machine Code's `datamachine_code_homeboy_available` option synced with CLI availability
+- `AGENTS.md` recomposed so the conditional Homeboy guidance appears for coding agents
+
+Verification commands:
+
+```bash
+homeboy --version
+homeboy extension list
+homeboy project show <project-id>
+homeboy project components list <project-id>
+wp option get datamachine_code_homeboy_available --path=/path/to/wordpress
+wp datamachine memory compose AGENTS.md --path=/path/to/wordpress
+```
+
+For WordPress Studio installs, use Studio's WP-CLI wrapper for the WordPress commands:
+
+```bash
+studio wp option get datamachine_code_homeboy_available
+studio wp datamachine memory compose AGENTS.md
+```
+
 ## Why Root? (VPS only)
 
 wp-coding-agents defaults to running the agent as `root` on VPS installs. On a single-purpose agent VPS, root keeps things simple:
diff --git a/skills/upgrade-wp-coding-agents/SKILL.md b/skills/upgrade-wp-coding-agents/SKILL.md
@@ -10,6 +10,8 @@ compatibility: "Requires a wp-coding-agents repo clone and an existing setup. Wo
 
 By default it also updates the setup-installed Data Machine plugins (`data-machine`, `data-machine-code`) to their latest version tags when those plugins are git checkouts. Use `--skip-plugins` to preserve the previous no-plugin-update behavior.
 
+If the install was created with the optional Homeboy layer, upgrade should preserve that model: the WordPress site root is the Homeboy **project**, primary Data Machine Code workspace checkouts are attached **components**, and `repo@branch` worktrees remain skipped by default. Homeboy is external to wp-coding-agents; do not vendor it or treat the site root as a component during upgrade guidance.
+
 ## When to use
 
 The user says something like:
@@ -46,13 +48,26 @@ The user says something like:
    ```
    Passing output (`OK — ... scenario(s)`) proves `dm-context-filter` still strips the Kimaki-only prompt sections the Data Machine agent should not see. If this fails after a Kimaki upgrade, fix the filter or refresh snapshots intentionally before calling the upgrade healthy.
 
+7. **Verify Homeboy when the install uses it.** Only do this when the user enabled Homeboy or `AGENTS.md` contains the Homeboy section. Run the project/component checks and pass failures through clearly:
+   ```bash
+   homeboy --version
+   homeboy extension list
+   homeboy project show <project-id>
+   homeboy project components list <project-id>
+   wp option get datamachine_code_homeboy_available --path=/path/to/site
+   wp datamachine memory compose AGENTS.md --path=/path/to/site
+   ```
+   For WordPress Studio installs, use `studio wp option get datamachine_code_homeboy_available` and `studio wp datamachine memory compose AGENTS.md`. Do not create `homeboy.json` in the site root to "fix" a missing project; that confuses a Homeboy project with a component.
+
 Run `./upgrade.sh --help` for scope flags (`--plugins-only`, `--skip-plugins`, `--kimaki-only`, `--skills-only`, `--agents-md-only`, `--repair-opencode-json`, etc.) and the full list of what the script touches and never touches.
 
 ## Never do
 
 - **Never restart the chat bridge automatically.** It kills active sessions including the one you're talking in.
 - **Never skip the dry-run** on a live install.
 - **Never touch user state:** `opencode.json` (the script does additive-only repair), the WordPress DB, nginx, SSL certs, `~/.kimaki/` auth state and OAuth tokens, the DM workspace cloned repos, or agent memory files (`SOUL.md` / `MEMORY.md` / `USER.md`).
+- **Never vendor Homeboy** into wp-coding-agents or scaffold `homeboy.json` in the WordPress site root. The site root is a Homeboy project; component metadata belongs in attached primary workspace repos.
+- **Never auto-attach `@` worktrees** as Homeboy components during upgrade. They are task-specific DMC worktrees and are skipped by default.
 - **Never hardcode workspace paths** (`/var/lib/...`, `/opt/...`, `/var/www/...`, `/root/...`) in commands you give the user. Use `git rev-parse --show-toplevel`, `$(npm root -g)`, `$KIMAKI_DATA_DIR`, and the script's auto-detection.
 
 ## Source of truth
diff --git a/skills/wp-coding-agents-setup/SKILL.md b/skills/wp-coding-agents-setup/SKILL.md
@@ -45,15 +45,27 @@ This skill is for the **local agent** (Claude Code, Cursor, etc.) assisting with
 > - **Telegram** — Your agent gets a Telegram bot (via @grinev/opencode-telegram-bot). OpenCode only.
 > - **No chat bridge** — Run the agent manually via SSH or terminal when needed."
 
-### Question 4: Agent Name
+### Question 4: Homeboy Developer Layer
+
+> "Do you want the optional **Homeboy developer layer** enabled with `--with-homeboy`?
+>
+> - Recommended for developers who want repo-aware checks, project status, review loops, and WordPress extension verification.
+> - Homeboy is an external CLI; wp-coding-agents does not bundle or vendor it.
+> - Setup treats the WordPress site root as the Homeboy **project**, not a component.
+> - Data Machine Code primary workspace checkouts become attached Homeboy **components** when they already have `homeboy.json`.
+> - Data Machine Code `repo@branch` worktrees are skipped by default because they are task-specific."
+
+If they say yes, add `--with-homeboy` to the setup command. Do not imply this is required for wp-coding-agents; it is a recommended power layer for code-heavy installs.
+
+### Question 5: Agent Name
 
 > "What would you like to name your agent? This becomes the agent slug used by Data Machine for identity and memory files.
 >
 > Default: derived from your site domain (e.g., `example` for example.com, `my-site` for my-site.local)"
 
 Maps to `--agent-slug <name>`. If the user is happy with the default, skip this flag.
 
-### Question 5: Server/Local Details
+### Question 6: Server/Local Details
 
 **For VPS installs:**
 
@@ -66,7 +78,7 @@ Maps to `--agent-slug <name>`. If the user is happy with the default, skip this
 
 > "Where is WordPress installed on your machine? (e.g., `~/Studio/my-wordpress-website`, `/Applications/MAMP/htdocs/wordpress`)"
 
-### Question 6: For Existing WordPress
+### Question 7: For Existing WordPress
 
 If they chose existing WordPress (VPS or local):
 
@@ -90,6 +102,7 @@ Based on their answers, construct the appropriate command:
 | **Local + Claude Code + DM** | `EXISTING_WP=~/Studio/my-site ./setup.sh --local --runtime claude-code` |
 | **Local + Studio Code + DM** | `EXISTING_WP=~/Studio/my-site ./setup.sh --local --runtime studio-code` |
 | **Local + multiple runtimes** | `EXISTING_WP=~/Studio/my-site ./setup.sh --local --runtime claude-code,studio-code` |
+| **Local + recommended Homeboy layer** | `EXISTING_WP=~/Studio/my-site ./setup.sh --local --with-homeboy` |
 | **Local + DM + Telegram** | `EXISTING_WP=~/Studio/my-site ./setup.sh --local --chat telegram` |
 | **Local + DM, no chat** | `EXISTING_WP=~/Studio/my-site ./setup.sh --local --no-chat` |
 | **Local (Studio) with WP_CMD** | `WP_CMD="studio wp" EXISTING_WP=~/Studio/my-site ./setup.sh --local` |
@@ -102,6 +115,7 @@ Add `--skip-ssl` to skip Let's Encrypt certificate.
 Add `--root` to run the agent as root (default is dedicated service user).
 Add `--no-skills` to skip WordPress agent skills.
 Add `--agent-slug <slug>` to override the Data Machine agent slug.
+Add `--with-homeboy` when the user wants the optional Homeboy developer power layer. Homeboy remains external; setup should verify or install the CLI and WordPress extension, create/update a Homeboy project for the WordPress site root, attach eligible Data Machine Code primary workspace checkouts as components, skip `@` worktrees by default, sync `datamachine_code_homeboy_available`, and recompose `AGENTS.md`.
 
 **WordPress Studio note:** If the site runs under WordPress Studio, prefix the command with `WP_CMD="studio wp"` so setup.sh uses Studio's WP-CLI wrapper instead of bare `wp`. Studio is auto-detected when `studio` CLI and `STUDIO.md` are both present.
 
@@ -245,6 +259,46 @@ grep 'kimaki-config: WARNING' "$HOME/.kimaki/kimaki.log" || true
 
 If either `test -f` command fails, restart/re-run setup or upgrade before trusting a new OpenCode session. If the log contains a warning about the persistent plugin source dir or required OpenCode plugins, `dm-context-filter.ts` is not guaranteed to be active after restart.
 
+### Homeboy (`--with-homeboy`)
+
+If setup used `--with-homeboy`, verify the optional developer layer explicitly:
+
+```bash
+homeboy --version
+homeboy extension list
+homeboy project show <project-id>
+homeboy project components list <project-id>
+```
+
+Then verify Data Machine Code can see Homeboy and agent instructions were recomposed:
+
+**VPS or standard WP-CLI:**
+```bash
+wp option get datamachine_code_homeboy_available --path=/path/to/site
+wp datamachine memory compose AGENTS.md --path=/path/to/site
+```
+
+**WordPress Studio:**
+```bash
+studio wp option get datamachine_code_homeboy_available
+studio wp datamachine memory compose AGENTS.md
+```
+
+Expected model:
+
+```text
+WordPress site root
+  = Homeboy project
+
+DMC workspace primary checkouts
+  = Homeboy components attached to that project
+
+DMC worktrees (`repo@branch`)
+  = task-specific ephemeral worktrees skipped by default
+```
+
+Do not create `homeboy.json` in the WordPress site root. Do not attach `repo@branch` worktrees by default. Do not modify external component repos unless the user explicitly asks for a Homeboy adoption flow in that repo.
+
 ### Site Reachable (VPS)
 
 ```bash
@@ -325,6 +379,8 @@ Use when the user says things like:
 - "Add Claude Code / OpenCode to my existing WordPress site"
 - "Set up a local AI agent on my machine"
 - "Install wp-coding-agents with WordPress Studio"
+- "Set it up with Homeboy"
+- "Enable repo-aware Homeboy workflows"
 
 **Do NOT use** for ongoing WordPress management — that's the agent's job after installation.
 
@@ -341,3 +397,4 @@ Use when the user says things like:
 - **Telegram bot won't respond:** Verify `TELEGRAM_BOT_TOKEN` and `TELEGRAM_ALLOWED_USER_ID` are set, check that both `opencode-serve` and `opencode-telegram` services are running
 - **Data Machine not working:** Verify plugin active, run `wp action-scheduler run --allow-root` (VPS) or `studio wp action-scheduler run` (local)
 - **Runtime not found:** Check available runtimes with `ls runtimes/`, or install one (`npm install -g opencode-ai` or `npm install -g @anthropic-ai/claude-code`)
+- **Homeboy not available in AGENTS.md:** Verify `homeboy --version`, confirm `homeboy extension list` includes the WordPress extension, update `datamachine_code_homeboy_available`, then re-run `wp datamachine memory compose AGENTS.md` or `studio wp datamachine memory compose AGENTS.md`
