Problem
An agent working in a git worktree of a consumer project needed to run e2e tests. The test runner's webServer config reuses an already-running local server rather than starting a fresh one. The agent had to reason through, from scratch, that:
- the worktree's own dev server isn't running, but the main checkout's
adj-supervised instance is, on a fixed port
- if it let the e2e runner "reuse" that port, it would test the main checkout's code under the worktree's test run
- the fix was to boot an unsupervised dev server on an alternate port and point the e2e run at that
That workaround reintroduces exactly what Adjacent exists to prevent — an unlogged, unsupervised process outside the daemon's lifecycle — instead of registering a worktree instance (adj add --label) and pointing the e2e run at <label>.<name>.adj.ac.
Root cause
adj agent-instructions (crates/adj/src/agent_docs.rs) is the only steering doc consumer-project agents see, and it says nothing about:
- worktrees at all — no mention that
adj add inside a linked worktree gets its own routed hostname, process, port, and logs
- e2e/test-runner integration — no guidance on pointing a
webServer/reuseExistingServer-style config at the adj-proxied hostname instead of a bespoke local port
The README's "Worktrees" section (lines 79–85) and "Agent Integration" section exist independently; nothing connects them for an agent deciding how to run tests against a worktree instance.
Proposal
Extend the agent-instructions template (and/or the README) with a short section covering:
- worktree instances get their own hostname/port/process — don't spin up a second unsupervised server for one
- for test runners that reuse an existing local server by port (Playwright's
webServer.reuseExistingServer is the common case), point baseURL/webServer.url at the instance's <name>.adj.ac (or <label>.<name>.adj.ac in a worktree) instead of hardcoding a port
Acceptance criteria
Problem
An agent working in a git worktree of a consumer project needed to run e2e tests. The test runner's
webServerconfig reuses an already-running local server rather than starting a fresh one. The agent had to reason through, from scratch, that:adj-supervised instance is, on a fixed portThat workaround reintroduces exactly what Adjacent exists to prevent — an unlogged, unsupervised process outside the daemon's lifecycle — instead of registering a worktree instance (
adj add --label) and pointing the e2e run at<label>.<name>.adj.ac.Root cause
adj agent-instructions(crates/adj/src/agent_docs.rs) is the only steering doc consumer-project agents see, and it says nothing about:adj addinside a linked worktree gets its own routed hostname, process, port, and logswebServer/reuseExistingServer-style config at the adj-proxied hostname instead of a bespoke local portThe README's "Worktrees" section (lines 79–85) and "Agent Integration" section exist independently; nothing connects them for an agent deciding how to run tests against a worktree instance.
Proposal
Extend the
agent-instructionstemplate (and/or the README) with a short section covering:webServer.reuseExistingServeris the common case), pointbaseURL/webServer.urlat the instance's<name>.adj.ac(or<label>.<name>.adj.acin a worktree) instead of hardcoding a portAcceptance criteria
adj agent-instructionsoutput mentions worktree instances and how to address themagent_docs.rsunit test asserts the new section renders