feat: docker-agent.yaml config autodiscovery

[joshbarrington]

Closes: #2435

This allows auto config file discovery for docker-agent.yaml and docker-agent.yml in the current working directory.

Currently docker agent new leverages an agentic "creator" to build and write the config yaml file to disk. Here we specificy the fixed name in the instruction as opposed to the arbitrary name it previously would generate.

[joshbarrington]

@aheritier would be good to get a review when you have time.

[joshbarrington]

@dgageot this is ready when you have time for review.

Currently it just leverages an agent to write the config file when running docker new, as that's the existing behaviour.

[dgageot]

Hi @joshbarrington, thanks for the contribution! I'm not sure I would mix the work on default agents with the creator agent. Also, maybe it's better to consider .agents/docker-agent.yaml or .agents/default-agent.yaml as the default agent. wdyt?

[joshbarrington]

@dgageot point 2 in issue #2435 is scaffolding with docker agent new - running this process already leverages the creator agent to generate a new agent yaml file based on the description provided by the user, it generates it with a random (in context) name.

This just means the output file will save as docker-agent.yaml instead. What do you think is a better alternative? We write the in-built defaults to a file?

My interpretation of the issue implied the docker-agent.yaml should live in the root of the working directory synonymous to what you expect with a docker-compose.yaml and running docker compose, but can move it over into .agents/ if you think is best.

[joshbarrington]

@dgageot let me know what you think.

[aheritier]

Review Summary

The implementation is clean, well-tested, and CI is green. However, before merging, we need to align on the discovery algorithm design — the current scope (CWD-only) leaves important UX questions unanswered that will be harder to change later once users depend on the behavior.

✅ What's good

• Clean separation: autodiscoverConfigFile() is isolated and testable
• Proper precedence: explicit arg > autodiscovery > built-in default
• .yaml takes priority over .yml — good deterministic behavior
• Tests cover the key scenarios (discover yaml, yml, precedence, explicit override)
• CI passes (build, lint, tests, license)

🚫 Blocking: Discovery scope needs design decision

The current implementation only checks the current working directory. This raises critical questions:

1. Should discovery walk up the directory tree?

Most tools with config autodiscovery (git, eslint, docker-compose with --project-directory, rustfmt, etc.) traverse upward from CWD until they find a config or hit /. If a user runs docker agent from /project/src/services/, should we find /project/docker-agent.yaml?

Recommendation: For v1, CWD-only is acceptable if clearly documented, but we should at minimum document this as a known limitation and track upward traversal as a follow-up. The docker-compose analogy in the issue suggests users will expect to run from subdirectories.

2. Should .agents/ folder be checked?

Per @dgageot's suggestion — while not required for MVP, if we later add .agents/ support, it changes the search order. We should decide now whether the algorithm is:

CWD/docker-agent.yaml → CWD/docker-agent.yml → fallback

or:

CWD/docker-agent.yaml → CWD/docker-agent.yml → CWD/.agents/docker-agent.yaml → CWD/.agents/docker-agent.yml → fallback

This doesn't need implementation now, but the design should be decided so we don't paint ourselves into a corner.

3. Relative path resolution when discovered from a parent directory

The good news: fileSource.ParentDir() already returns filepath.Dir(path), meaning relative paths in the config resolve relative to the config file's location, not CWD. This is correct behavior and will work well if we add upward traversal later.

Non-blocking suggestions

See inline comments below.

[aheritier]

Additional design input from @aheritier

Summarizing the open design questions that need resolution before merge:

Discovery Algorithm — What should the final behavior be?

Option A (current PR): CWD-only lookup

CWD/docker-agent.yaml → CWD/docker-agent.yml → built-in default

Option B: CWD + .agents/ subfolder

CWD/docker-agent.yaml → CWD/docker-agent.yml → CWD/.agents/docker-agent.yaml → CWD/.agents/docker-agent.yml → built-in default

Option C: Recursive upward traversal (like git/eslint)

For each dir from CWD up to /:
  dir/docker-agent.yaml → dir/docker-agent.yml → (optionally dir/.agents/docker-agent.y[a]ml)
→ built-in default

Context from @aheritier:

The .agents/ idea is interesting but not something originally scoped — Claude's CLAUDE.md doesn't support subfolder discovery, while GitHub Copilot's AGENTS.md supports both root and subfolder.

The critical question is: if we do recursive discovery from CWD up to /, should we also check .agents/ at each level? And what's the relative path behavior if docker agent run is launched from a subdirectory?

My analysis on relative paths:

Good news — fileSource.ParentDir() already resolves to the directory containing the config file (not CWD). So if recursive discovery finds /project/docker-agent.yaml while CWD is /project/src/, relative paths like ./instructions.txt in the config will correctly resolve to /project/instructions.txt. This is the right behavior and matches docker-compose semantics.

Recommendation:

1. For this PR: Ship with CWD-only (Option A) but add a code comment documenting this as intentional scope limitation
2. Follow-up issue: Track recursive upward traversal as enhancement (probably needed for docker-compose-like UX)
3. .agents/ folder: Decide separately — it's orthogonal to upward traversal

@joshbarrington @dgageot — would appreciate alignment on which option to target for v1.

[joshbarrington]

@aheritier thanks for the review. Happy to continue with your recommendations (and add the comment), or integrate points 2 and 3 into this PR. @dgageot let us know your thoughts and I can proceed accordingly.