Build GitHub + Docker Agent Extension: Pages, Workflows, and Merge Conflict Agent

[fractional-pm]

Goal

Build a lightweight GitHub + Docker Agent Extension that can be installed across small repos without embedding a large repo-local runtime.

Scope

1. GitHub Page / Docs Site

Create a GitHub Pages-ready docs site for the extension.

Suggested content:

• Overview
• Install GitHub App
• Install Docker Extension
• Supported /agent commands
• Security model
• Repo config via AGENTS.md
• Optional .github/repo-agent.yml
• Merge conflict workflow
• CI/workflow troubleshooting

2. GitHub Workflow Support

Add reusable GitHub workflows for repos that want local execution.

Required workflows:

• .github/workflows/agent.yml
  • Supports workflow_dispatch
  • Supports issue comments containing /agent
  • Supports pull request review/analyze flows
• .github/workflows/pages.yml
  • Builds and deploys docs to GitHub Pages
• .github/workflows/docker-extension.yml
  • Builds Docker extension image
  • Optionally publishes image/artifact

3. Merge Conflict Agent

Add an agent workflow for detecting and helping resolve merge conflicts.

Supported commands:

• /agent merge-check
• /agent resolve-conflict
• /agent explain-conflict

Initial behavior:

• Detect whether PR is mergeable
• Identify conflicting files when possible
• Comment with explanation and recommended resolution
• Avoid force-pushes in v1
• Never auto-resolve conflicts without explicit approval

4. Docker Extension

Add local Docker Desktop extension shell.

Capabilities:

• List running containers
• Inspect service logs
• Detect common compose failures
• Explain Dockerfile / compose issues
• Connect local findings back to GitHub issue or PR

5. Shared Agent Core

Create shared packages:

• packages/agent-core
• packages/github-tools
• packages/docker-tools
• packages/llm-provider

Proposed repository structure

agent-extension/
├── apps/
│   ├── github-app/
│   └── docker-extension/
├── packages/
│   ├── agent-core/
│   ├── github-tools/
│   ├── docker-tools/
│   └── llm-provider/
├── docs/
├── examples/
│   └── tiny-repo/
│       ├── AGENTS.md
│       └── .github/repo-agent.yml
└── .github/workflows/
    ├── agent.yml
    ├── pages.yml
    └── docker-extension.yml

MVP checklist

• Create monorepo scaffold
• Add GitHub Pages docs
• Add Pages deploy workflow
• Add agent command parser
• Add /agent analyze
• Add /agent review
• Add /agent fix-ci
• Add /agent merge-check
• Add /agent explain-conflict
• Add Docker Extension metadata
• Add Docker backend stub
• Add Docker UI stub
• Document security policy

Safety policy

• No direct pushes to main
• No destructive file changes without approval
• No secret printing
• No production deploys
• Merge conflict resolution must open a PR or comment with instructions, not silently force-update branches

Notes

This should be an extension-first architecture. Small repos only need AGENTS.md and optional .github/repo-agent.yml; the heavy runtime stays in the hosted GitHub/Docker extension.