homeracker

# 🔄 Sync Agent Instructions

## 📌 What

Downloads the canonical agent instruction set from [kellerlabs/homeracker](https://github.com/kellerlabs/homeracker) and overwrites local copies.

Synced files:

- `AGENTS.md`: the canonical repo-wide instructions, read by every coding agent
- `CLAUDE.md`: pointer to `AGENTS.md`, imported by Claude Code
- `.claude/rules/*.md`: all path-specific guidelines (discovered dynamically via GitHub API)
- `.github/pull_request_template.md`: PR template

`AGENTS.md` and `CLAUDE.md` must stay in the same sync set. A pointer that arrives without its target dangles.

A successful sync also deletes `.github/instructions/` and `.github/copilot-instructions.md` if the consumer still has them. The guidelines live in `.claude/rules/` now and agents read `AGENTS.md` directly, so a repo holding the old paths applies each rule twice and keeps an entry point that no longer receives updates. The script carries a `TODO` marking this prune for removal once every consumer has synced once.

### Requirements

- `curl`, `jq`, both pre-installed on GitHub Actions runners
- `GITHUB_TOKEN` (optional), used for API authentication to avoid rate limits; automatically available in GitHub Actions via `${{ github.token }}`

## 🤔 Why

HomeRacker maintains a well-proven, optimized instruction set that ensures consistent AI behavior across all repos. Instead of maintaining diverging copies, downstream repos can sync from the single source of truth.

Current consumers:

- **homeracker-exclusive**: syncs daily via CI + manual trigger
- **homeracker-community**: planned

## 🔧 How

### One-liner (remote execution)

```bash
curl -fsSL https://raw.githubusercontent.com/kellerlabs/homeracker/main/.github/actions/sync-instructions/sync-instructions.sh | bash
```

Pass a ref to sync from a specific branch or tag:

```bash
curl -fsSL https://raw.githubusercontent.com/kellerlabs/homeracker/sync-instructions-v1.0.0/.github/actions/sync-instructions/sync-instructions.sh | bash -s -- sync-instructions-v1.0.0
```

### Reusable action

```yaml
- uses: kellerlabs/homeracker/.github/actions/sync-instructions@sync-instructions-v1.0.0
  with:
    ref: main  # optional, defaults to main
```

The action only downloads files, it does not commit. The caller workflow handles git operations.

### Example workflow

```yaml
name: Sync Agent Instructions
on:
  schedule:
    - cron: '0 6 * * 1'  # weekly Monday 06:00 UTC
  workflow_dispatch:

permissions:
  contents: write

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: kellerlabs/homeracker/.github/actions/sync-instructions@sync-instructions-v1.0.0

      - name: Commit and push
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          if git diff --cached --quiet; then
            echo "No changes to commit"
          else
            git commit -m "ci(instructions): sync from homeracker"
            git push
          fi
```

### Versioning

The action is tagged following the `sync-instructions-v<major>.<minor>.<patch>` convention (managed by release-please). Renovate picks up tag updates automatically.

## 📚 References

- [GitHub docs: Repository custom instructions](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot)
- [VS Code docs: Custom instructions](https://code.visualstudio.com/docs/copilot/copilot-customization)