Skip to content

Workflow

hoseboy is developed agents-driven: most changes are made by coding agents working from a GitHub issue, in an isolated worktree, verified before they are opened as a PR. The process below is written so that a human and an agent follow the same steps.

The cycle

flowchart LR
    I[Issue] --> B[Branch in a worktree]
    B --> W[Work]
    W --> C[compile-check]
    C -->|fails| W
    C -->|passes| PR[gh pr create]
    PR --> R[Review]
    R --> M[Squash merge]
    M --> X[Cleanup worktree + branch]

1. Issue first

Every change starts as an issue, including refactors and docs. The issue number becomes part of the branch name, so there is always a path from a line of code back to the reason it exists.

gh issue create --title "Wire the water gauge into demo.unity" --body "..."

Write issues with enough context that an agent can act on them without the conversation that produced them — file paths, the component names involved, and what "done" looks like.

2. Branch in a worktree

Never work in the main checkout. Unity holds a lock on Library/, and switching branches underneath a running editor triggers a full reimport at best. Each task gets its own worktree, which means its own Library/ and its own editor instance.

Worktrees live under C:\Users\wkeif\Documents\GitHub\hoseboy-wt\.

cd C:\Users\wkeif\Documents\GitHub\hoseboy
git worktree add -b feat/42-water-gauge C:\Users\wkeif\Documents\GitHub\hoseboy-wt\42-water-gauge main

Branch naming: feat/<issue-number>-slug. Other prefixes as appropriate — fix/, docs/, chore/ — but the issue number always comes first in the slug.

The first Unity open in a fresh worktree re-imports the whole project. That is the cost of isolation and it is worth paying.

3. Work

  • Scene and prefab changes are YAML diffs. Keep them small and keep them separate from code changes where you can — a PR that touches both a script and demo.unity is much harder to review.
  • Follow coding conventions.
  • If you add a component that must run at a particular point in the frame, put it in the execution-order table and say why in the class comment. That table is load-bearing.

4. Compile check

Before opening a PR, verify the project compiles:

.\tools\compile-check.ps1

Not committed yet

tools/compile-check.ps1 does not exist in the repo. Until it does, verify by opening the worktree in Unity and confirming a clean console, or by driving the editor through MCP for Unity. Adding the script is tracked work.

What it needs to do: launch the editor in batch mode against the worktree, force a script compile, and exit non-zero on any compiler error. There are no tests to run, so compilation is the entire gate.

5. Pull request

gh pr create --base main --title "Wire the water gauge into demo.unity" --body "Closes #42"

PR description should say what changed, what was verified, and what was deliberately left out. Link the issue with Closes #<n> so merging closes it.

Do not merge your own PR without review, and do not merge from the agent that wrote it.

6. Squash merge

Squash merge, always. History stays one commit per issue, which keeps git log readable and makes reverting a change a single operation. The squash commit message is the PR title plus the issue reference.

Commit message style, matching existing history:

added(fluid meter): fixed UI

<verb>(<area>): <what>. Lowercase, present or past as it reads naturally.

7. Cleanup

cd C:\Users\wkeif\Documents\GitHub\hoseboy
git worktree remove C:\Users\wkeif\Documents\GitHub\hoseboy-wt\42-water-gauge
git branch -d feat/42-water-gauge
git worktree prune

Stale worktrees each carry a multi-gigabyte Library/. Remove them when the PR merges.

Agents-driven development

Most work on this project is done by coding agents, so the process is built around what agents need:

  • Issues are the interface. An agent should be able to pick up an issue and act on it without reading a conversation. Vague issues produce vague changes.
  • Worktrees are the isolation boundary. Several agents can work at once without fighting over Library/ or the branch checked out in the main tree. The main checkout stays clean and is used for nothing but coordination.
  • Compile check is the contract. With no test suite, "it compiles" is the automatic gate and human review is the real one. Adding tests would change this; nothing else would.
  • MCP for Unity (com.coplaydev.unity-mcp) lets an agent drive the editor directly — scene inspection, component wiring, play-mode checks. That is how the "wire X into the scene" issues in wave 1 get done without a human clicking through the inspector.
  • Documentation is part of the change. A PR that changes how a system works updates its page under docs/systems/ in the same PR. Docs deploy from main automatically — see Docs site.