QUICKSTART.md

Groundkeeper - Quick Reference

What is Groundkeeper?

Groundkeeper is a deterministic repository maintenance agent that executes a six-stage pipeline to produce structured reports:

1. Preflight
2. Analysis
3. Plan
4. Patch
5. Verify
6. Publish

Quick Start (30 seconds)

# Install globally
npm install -g groundkeeper

# Run with a config file
groundkeeper run --config .github/agent.yml

# Check the report
cat .groundkeeper/report.md

CLI Commands

Command	Description
groundkeeper run	Run the full stage pipeline and generate a report

Common options:

groundkeeper run --config .github/agent.yml --directory .

Configuration File

Create .github/agent.yml in your repository root and validate it against packages/schemas/agent.schema.json:

$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

GitHub Action Usage

Add to .github/workflows/groundkeeper.yml:

name: Repository Maintenance

on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly
  workflow_dispatch:

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

Output

Reports are saved to .groundkeeper/ directory:

• report.md - Markdown format (default)
• report.json - JSON format (if enabled)

Safety Features

✅ Read-only by default - Won't modify your repo ✅ No auto-merge - All changes require review ✅ Deterministic - Same input = same output ✅ YAML spec - All behavior is explicit ✅ Stage-based - Clear execution flow

Need Help?

• Documentation: See README.md
• Contributing: See CONTRIBUTING.md
• Issues: GitHub Issues

License

MIT License - see LICENSE