# Dogfooding

Maven Tools MCP runs its own dependency agent against this repository on a schedule. The goal is intentionally modest: safe, reviewable dependency upkeep rather than full autonomous upgrades.

## What The Workflow Does

The workflow is [`dependency-agent-self-update.yml`](../.github/workflows/dependency-agent-self-update.yml).

On each scheduled or manual run it:

1. Starts the Maven Tools MCP HTTP sidecar with `arvindand/maven-tools-mcp:latest-http`
2. Runs the local Python agent in [`agents/copilot-maven-tools-agent/`](../agents/copilot-maven-tools-agent/)
3. Hands the raw `pom.xml` to the `recommend_pom_upgrades` MCP tool and applies the returned `deterministicActions[]` directly
4. Ignores dependencies that are intentionally pinned for temporary operational reasons
5. Creates or updates a persistent PR branch: `bot/dependency-agent-self-update`
6. Relies on normal repository CI to validate the resulting PR

Major updates, multi-BOM conflicts, and explicit overrides land in `needsAttention[]` and are not auto-applied. Manual `major` mode runs route the analysis through the Copilot SDK so the model can frame migration risk and review context without touching the deterministic weekly update path.

## Agent Layout

The dependency agent lives in [`agents/copilot-maven-tools-agent/`](../agents/copilot-maven-tools-agent/).

It is a local Python subproject that:

- reads the repository `pom.xml` and hands it to the `recommend_pom_upgrades` MCP tool
- applies the returned `deterministicActions[]` directly, using exact property metadata when a
  root dependency-management or plugin dependency declaration owns the version, and owner-plugin
  metadata to scope literal plugin dependency edits
- displays `needsAttention[]` (majors, conflicts, explicit overrides) for visibility
- uses the Copilot SDK only in major-review mode
- leaves PR creation to GitHub Actions

That split keeps the agent focused on applying server-decided edits while GitHub Actions handles branch and PR mechanics. Apache Maven on the server is the source of truth for resolution. The client uses Expat to locate XML declarations, checks each current value and owner, and applies byte-span edits without reformatting the POM. Shared-property edits require consistent authorization for all affected references; stale, ambiguous or unsupported edits are reported instead of guessed.

## Deterministic And Major Modes

Routine `minor_patch` runs use a direct MCP JSON-RPC client. The workflow sends one `recommend_pom_upgrades` call with the raw POM XML, attempts each entry in `deterministicActions[]` subject to the exact-edit checks, and surfaces `needsAttention[]` for the PR description. There is no model session in that path and no per-coordinate fan-out.

`major` mode is report-only and uses the GitHub Copilot SDK with Maven Tools MCP attached. That keeps model judgement available for breaking-change context, migration planning, and ambiguous ecosystem decisions while making sure the weekly self-update PR remains deterministic.

This gives the project direct control over:

- MCP client lifecycle for deterministic updates
- prompt/tool orchestration only where it adds value
- output parsing and version filtering
- portability to other AI providers later if needed

The result is a small reference implementation for tool-first dependency automation, with an AI session reserved for major-upgrade judgement rather than routine version bumps.

## Parallel To GitHub Agentic Workflows

The shape is similar to GitHub Agentic Workflows:

- GitHub Actions orchestrates the run
- a bounded tool client performs deterministic minor/patch updates
- an AI client is reserved for report-only major-upgrade review
- the result is a reviewable PR

The difference is that this repository uses a hand-authored workflow plus a purpose-built Python agent rather than a compiled workflow format.

That makes this workflow a practical precursor, not just a comparison point. It already demonstrates the core pattern in a narrow, useful domain: structured dependency intelligence feeding a bounded tool task inside CI, with model judgement available only for major-upgrade planning and the output constrained to a reviewable pull request. In that sense, the dogfooding setup is an example of how a larger GitHub Agentic Workflows-style future can be approached incrementally with today's tooling.

## Required Setup

To use the same workflow in your fork or another repository:

1. Create a fine-grained PAT named `COPILOT_BOT_PAT`
2. Grant these repository permissions:
   - Contents: write
   - Pull requests: write
   - Metadata: read
3. Grant GitHub Copilot "Requests" permission if you want manual `major` mode reports
4. Add the token as a repository secret in **Settings -> Secrets and variables -> Actions**

## Manual Trigger

### GitHub UI

Open **Actions -> Dependency Agent Self-Update -> Run workflow**.

### GitHub CLI

```bash
gh workflow run dependency-agent-self-update.yml
```

Dry run (analyze only, no PR):

```bash
gh workflow run dependency-agent-self-update.yml -f dry_run=true
```

Major review mode:

```bash
gh workflow run dependency-agent-self-update.yml -f mode=major -f dry_run=true
```

## Operational Notes

- `CONTEXT7_API_KEY` is optional for the HTTP sidecar image
- scheduled runs default to `minor_patch` mode and do not require a Copilot SDK session
- manual `major` runs are dry-run/report-only by convention and require Copilot Requests permission
- the workflow keeps a single persistent bot branch instead of creating a new branch every run
- application-error payloads stop the direct MCP path rather than being interpreted as an empty upgrade plan
- repository CI remains the source of truth for build verification
- temporary dependency overrides should be added to the workflow ignore list when they should not be auto-updated

## Related Docs

- [`setup.md`](setup.md)
- [`tools.md`](tools.md)
- [`examples.md`](examples.md)