Feature: Support project-level default config file autodiscovery (docker-agent.yaml)

[aheritier]

Overview

We propose adding support for project-level default config file autodiscovery to reduce CLI friction and improve discoverability of agent configurations in repositories.

Current Behavior

• Users must explicitly run docker agent run ./agent.yaml with a file argument
• The docker agent bare command defaults to run, but without a file argument, it falls back to the embedded built-in default agent rather than discovering a project-local config file
• This creates friction and reduces visibility of agent configurations within project repositories

Proposed Changes

1. Config File Autodiscovery

Support docker-agent.yaml or docker-agent.yml as autodiscovered defaults in the current directory. When users run:

docker agent

The command should:

1. Check for docker-agent.yaml or docker-agent.yml in the current directory
2. If found, use it as the default configuration
3. If not found, fall back to the embedded built-in default agent (current behavior)

2. Native Scaffolding

Update docker agent new to natively scaffold a docker-agent.yaml file instead of prompting for an arbitrary filename. This improves the initial setup experience and aligns user expectations with autodiscovery.

Benefits

• Better Discoverability: Developers immediately see agent configurations checked into their repository
• Reduced CLI Friction: Simpler command invocation (docker agent vs docker agent run ./agent.yaml)
• Alignment with Community Standards: Follows patterns established by tools like docker compose (docker-compose.yaml) and other ecosystem tools
• Improved Onboarding: New team members can run agents without consulting documentation for file paths

Future Considerations

• The AGENTS.yaml standard could serve as a future convention for project-level agent orchestration (avoiding conflicts with existing AGENTS.md documentation files)
• For now, recommend starting with docker-agent.yaml to minimize naming conflicts and maintain clarity

Implementation Notes

• Autodiscovery should work seamlessly with relative and absolute paths
• Consider XDG_CONFIG_HOME and other standard environment-based configuration discovery patterns for future extensibility
• Maintain backward compatibility with explicit file arguments (e.g., docker agent run ./custom-agent.yaml)

[joshbarrington]

@aheritier are you happy for me to have a go at implementing this?

I'd begin with an MR for 1. to enable the autodiscovery, if you agree that the native scaffolding can be left for a separate MR?

[dgageot]

@joshbarrington go!