Skip to content

agent-instructions doc doesn't cover worktree instances or e2e/webServer port reuse #78

Description

@nonreagent

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

  • adj agent-instructions output mentions worktree instances and how to address them
  • Output gives concrete guidance for e2e/test-runner configs that reuse an existing server by port
  • agent_docs.rs unit test asserts the new section renders

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions