feat(docker-agent): add Docker Agent integration

[nervgh]

Description

Closes #4301

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (if applicable)

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (describe below)

Assisted-by: OpenAI ChatGPT (model: GPT-5.6 Luna)

[Copilot]

Pull request overview

Adds Docker Agent as a skills-based integration with workflow dispatch support.

Changes:

• Registers Docker Agent and adds catalog/reference documentation.
• Implements CLI selection and execution arguments.
• Adds metadata and dispatch tests.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/specify_cli/integrations/docker_agent/__init__.py	Implements the integration.
src/specify_cli/integrations/__init__.py	Registers Docker Agent.
tests/integrations/test_integration_docker_agent.py	Adds integration tests.
integrations/catalog.json	Adds the catalog entry.
docs/reference/integrations.md	Documents usage.
AGENTS.md	Updates the architecture example.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Suppressed comments (2)

src/specify_cli/integrations/docker_agent/init.py:104

• The custom dispatch path also bypasses SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS. Custom dispatchers must apply the shared hook themselves, as demonstrated by CopilotIntegration.dispatch_command and its regression test (tests/integrations/test_extra_args.py:429-454); otherwise operator flags work in neither Docker Agent workflow path.

        exec_args = [*self._agent_command(), "--exec"]

src/specify_cli/integrations/docker_agent/init.py:29

• Plugin-only Docker Desktop installations cannot pass normal initialization: specify init calls check_tool("docker-agent"), while the shared check only looks up that executable (commands/init.py:575-579, _utils.py:133-141). Thus the supported docker agent form is rejected unless users bypass validation. Extend the preflight to accept and verify either docker-agent or the docker agent plugin instead of requiring --ignore-agent-tools.

        # Docker Agent is exposed as either `docker-agent` or `docker agent`.
        # The init command documents --ignore-agent-tools for the plugin form,
        # because the generic preflight check looks up the integration key.
        "requires_cli": True,

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/specify_cli/integrations/docker_agent/init.py:27

• Plugin-only Docker Agent installs cannot pass specify init: requires_cli=True makes init call check_tool("docker-agent"), while check_tool only probes that exact executable (src/specify_cli/_utils.py:133-141). This rejects the documented docker agent form even when docker is installed, despite _agent_command() supporting it at runtime. Please add Docker Agent detection that accepts either docker-agent or docker (with a regression test) rather than requiring every Docker Desktop user to bypass preflight with --ignore-agent-tools.

        # Docker Agent is exposed as either `docker-agent` or `docker agent`.
        # The init command documents --ignore-agent-tools for the plugin form,
        # because the generic preflight check looks up the integration key.
        "requires_cli": True,

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/specify_cli/integrations/docker_agent/init.py:56

• When an explicit override points to docker and the plugin probe fails or times out, this fallback drops the agent subcommand and later dispatches docker run --exec .... Because the workflow preflight sees the Docker executable, it proceeds and may treat the configured agent reference as a container image. Preserve the plugin-shaped argv for Docker overrides even on probe failure so the command fails as docker agent ... rather than invoking an unrelated Docker operation.

        if command is None:
            # Preserve the normal executable-shaped argv for dispatch callers;
            # preflight and the subprocess runner report the unavailable CLI.
            return [executable, "run"]