Groundkeeper

Groundkeeper is a deterministic, YAML-driven repository maintenance agent that runs primarily in GitHub Actions. It is designed to be safe, reviewable, and boring: every output is structured, validated, and generated under strict budgets and scope rules.

Philosophy & Safety

• YAML is the source of truth — .github/agent.yml defines scope, budgets, and runtime settings.
• Report-only by default — publishing is opt-in and gated by config.
• Deterministic stages — fixed stages with schema-validated I/O.
• No hidden automation — no auto-merge, no background services.
• Scoped execution — out-of-scope changes are rejected before LLM calls.

Features

• Schema-validated configuration via packages/schemas/agent.schema.json
• Strict stage boundaries: Preflight → Analysis → Plan → Patch → Verify → Publish
• Prompt templates per stage in prompts/
• CLI + GitHub Action wrapper for consistent automation

Repository Layout

• packages/cli — CLI entrypoint and command handling
• packages/core — stage runner, config validation, scope, and budgets
• packages/runtimes — LLM runtime adapters (OpenAI, Copilot)
• packages/schemas — agent config schema and stage I/O schemas
• prompts/ — stage prompt templates (analysis, plan, patch, verify, publish)

Installation

As a CLI tool

npm install -g groundkeeper

As a GitHub Action

Add to your workflow file (e.g., .github/workflows/groundkeeper.yml):

name: Repository Maintenance
on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday
  workflow_dispatch:

jobs:
  maintenance:
    runs-on: ubuntu-latest
    steps:
      - name: Run Groundkeeper
        uses: efremidze/groundkeeper@v1
        with:
          config: .github/agent.yml
          github-token: ${{ secrets.GITHUB_TOKEN }}

Quick Start

1. Create .github/agent.yml:

$schema: ../packages/schemas/agent.schema.json
version: '1.0'
mode: report-only

scope:
  include:
    - src/**
    - docs/**
    - README.md
  exclude:
    - node_modules/**
    - dist/**

budgets:
  maxFiles: 100
  maxDiffLines: 800
  maxTokens: 10000

rules:
  allow:
    - documentation
    - formatting
  deny:
    - dependency-upgrades

runtime:
  provider: openai

publish:
  enabled: false

2. Run Groundkeeper:

groundkeeper run --config .github/agent.yml

Usage

CLI Commands

groundkeeper run

Run the deterministic stage pipeline:

groundkeeper run [options]

Options:
  -c, --config <path>      Path to configuration file (default: ".github/agent.yml")
  -d, --directory <path>   Working directory (default: current directory)

Configuration

The configuration file is validated against packages/schemas/agent.schema.json. Groundkeeper reads .github/agent.yml as the source of truth by default.

Schema

version: string                # Configuration version (required)
mode: report-only              # Safety mode

scope:                          # Allowed repo paths
  include: [string]
  exclude: [string]

budgets:                        # Hard limits before LLM calls
  maxFiles: number
  maxDiffLines: number
  maxTokens: number

rules:                          # Allowed/denied rule categories
  allow: [string]
  deny: [string]

runtime:                        # LLM runtime selection
  provider: openai | copilot

publish:                        # Publishing behavior (opt-in)
  enabled: boolean
  target: pr | issue

Stages

Groundkeeper executes fixed stages with schema-validated inputs/outputs:

1. Preflight — deterministic repo metadata and validation (no LLM)
2. Analysis — read-only analysis (LLM)
3. Plan — plan only (LLM)
4. Patch — diff-only output (LLM)
5. Verify — runner executes checks; LLM interprets results
6. Publish — report content for PR/issue (LLM), published by CLI if enabled

Core Principles

YAML is the Spec

All behavior is defined in .github/agent.yml. This makes the agent's behavior explicit and version-controlled.

Read-only by Default

Groundkeeper will not publish changes unless publish.enabled is explicitly set to true.

Deterministic Output

Given the same repository state and configuration, Groundkeeper produces the same structured outputs.

No Direct Commits

Groundkeeper does not commit changes directly. Publishing is handled by the CLI and Action with explicit configuration.

No Auto-merge

Even when publishing, Groundkeeper never auto-merges.

Examples

Generate a maintenance report

groundkeeper run --config .github/agent.yml
cat .groundkeeper/report.md

Run in CI/CD

# .github/workflows/groundkeeper.yml
name: Weekly Maintenance
on:
  schedule:
    - cron: '0 0 * * 0'

jobs:
  groundkeeper:
    runs-on: ubuntu-latest
    steps:
      - uses: efremidze/groundkeeper@v1
        with:
          config: .github/agent.yml

Development

Setup

git clone https://github.com/efremidze/Groundkeeper.git
cd Groundkeeper
npm install

Build

npm run build

Run locally

npm start

Test

npm test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Author

Lasha Efremidze

---

Note: Groundkeeper is designed to be safe and non-intrusive. It won't make changes to your repository without explicit permission.