compozy/skeeper

Spec docs drift from code, or they bloat every PR. Skeeper picks neither.

It mirrors SPEC.md, ADRs, RFCs, and AI plan files into a sidecar Git repository and commits a tiny skeeper.lock to your main repo that pins every commit to exact sidecar commits. PR diffs stay focused on code, spec history stays auditable, and nothing silently drifts because the managed Git hooks fail the commit if the sidecar state cannot be proven.

✨ Highlights

• Lockfile-backed reliability. skeeper.lock records sidecar URL, source branch, namespace branch, sidecar commit, per-namespace digest, file count, and byte count.
• Strict managed hooks. The managed pre-commit and pre-merge-commit hooks sync staged content, push the sidecar, write and stage skeeper.lock, and fail closed. The managed pre-push hook verifies the lock against the sidecar remote.
• Specs stay local to their code. Edit SPEC.md, docs/specs/**, .claude/plans/**, ADRs, RFCs, or custom globs where they naturally belong.
• Shared sidecars without collisions. Namespaces isolate stored paths and sidecar branches inside one sidecar remote.
• Branch-aware history. Namespace branches use /__branches__/.
• Git-like spec sync. skeeper pull brings remote docs in, applies safe remote deletes, skeeper push publishes local docs and safe local deletes, and skeeper sync runs pull then push.
• Safe by default. Push rejects sidecar branches whose remote tip does not match the local skeeper.lock; destructive pruning without a known base still requires --prune.
• Fresh-clone restore. skeeper restore --all restores files from the exact sidecar commits recorded in skeeper.lock.
• Small command surface. Daily use is status, pull, push, sync, diff, reconcile, restore, track, untrack, repair, log, and version; Git hook plumbing lives behind hidden skeeper internal commands.
• Skill for AI agents. A bundled skill at skills/skeeper/SKILL.md teaches coding agents the strict-sync workflow, namespaces, and recovery commands.

🎯 Who Is This For

• Teams using AI coding agents that produce SPEC.md, PRD, TechSpec, and plan markdown next to code.
• Engineering organizations running ADRs, RFCs, and design docs in-repo without making every PR a docs+code review.
• Solo developers who want full spec history (git log, git blame, branches, PRs) without polluting their main repository’s diff.

📦 Installation

Homebrew

brew install compozy/compozy/skeeper

NPM

npm install -g @compozy/skeeper

Go

go install github.com/compozy/skeeper/cmd/skeeper@latest

GitHub Releases

Download the archive for your OS and architecture from GitHub Releases, then place the skeeper binary on your PATH.

From Source

git clone [email protected]:compozy/skeeper.git
cd skeeper
make verify
go build -o bin/skeeper ./cmd/skeeper

Docker

git clone [email protected]:compozy/skeeper.git
cd skeeper
make docker-build
docker run --rm -v "$PWD:/workspace" -w /workspace skeeper:dev status

Prerequisites:

• git on PATH
• gh only when skeeper init creates a new GitHub sidecar repo; existing sidecars can be reused with --sidecar

🔄 How It Works

Spec files live in the main worktree but are ignored by the main repository through a managed .gitignore block. The sidecar repository stores mirrored files under / and pushes them to /__branches__/.

On commit, the managed pre-commit block runs last. On automatic merge commits, the managed pre-merge-commit block runs the same strict sync path because Git does not run pre-commit for merge commits. Both hooks build a plan from the staged index plus explicitly owned ignored/untracked spec paths, fetch sidecar refs, verify the sidecar branch still matches skeeper.lock, mirror content into .skeeper/, commit and push the sidecar, write skeeper.lock, and stage that lock before Git creates the main commit.

flowchart TD
    Start([👤 git commit]):::user --> UserHook[🪝 Existing user hook content]:::user
    UserHook --> Block

    subgraph Block [📦 Skeeper pre-commit block]
        direction TB
        S1[🧮 Reconcile staged specs+ ownership] --> S2[🔄 Fetch & verifysidecar base]
        S2 --> S3[🪞 Mirror namespace filesinto .skeeper/]
        S3 --> S4[📤 Commit & push sidecar]
        S4 --> S5[🔒 Write & stageskeeper.lock]
    end

    Block --> Commit[✅ Main commit proceeds]:::ok
    Commit --> Push([🚀 git push]):::user
    Push --> Verify[🔍 Skeeper pre-push status check]:::skeeper
    Verify --> Done([🎉 Sidecar checked]):::ok

    classDef user fill:#dbeafe,stroke:#1d4ed8,color:#0c1e3e
    classDef skeeper fill:#fef3c7,stroke:#b45309,color:#3b2c00
    classDef ok fill:#dcfce7,stroke:#15803d,color:#052e16
    class S1,S2,S3,S4,S5 skeeper

If sync fails, the commit fails. This is intentional: a committed main change should not silently drift from the sidecar. The audited bypass is SKEEPER_SKIP=1; it records .git/skeeper/bypass.json, prints a warning, and status --check, repair, and the managed pre-push hook continue to surface stale-lock diagnostics until skeeper sync or skeeper repair repairs the state. git commit --no-verify is unsupported because Git skips all hook code and cannot record an audit trail.

⚙️ Configuration

skeeper init writes .skeeper.yml at the repository root. Commit it.

sidecar: [email protected]:user/myproject-specs.git

namespaces:
  - name: project
    patterns:
      - "**/SPEC.md"
      - "docs/specs/**"
      - ".claude/plans/**"
      - "**/*.spec.md"
    exclude:
      - "docs/specs/private/**"

Advanced operational defaults are optional:

settings:
  guardrails:
    max_files: 100
    max_bytes: 10485760
  hooks:
    pre_push_timeout: 30s
    allow_skip_env: SKEEPER_SKIP

namespaces:
  - name: generated
    patterns:
      - "generated/specs/**"
    respect_gitignore: false

Rules:

• Unknown keys are rejected.
• Every namespace needs a name and at least one glob in patterns.
• exclude is the only public exclusion mechanism. Negative globs in patterns are rejected.
• Ownership must be unique. If two namespaces own the same file, the plan fails and asks for an exclude fix.
• respect_gitignore: false bypasses root .gitignore, nested .gitignore, .git/info/exclude, and global excludes for that namespace. .git/ and .skeeper/ are always excluded.

Local-only state lives under .git/skeeper/:

🚀 Quick Start

skeeper init

Interactive init asks for the sidecar mode, repository name or URL, namespace, bootstrap command, and optional extra context globs. With flags:

skeeper init \
  --sidecar-name myproject-specs \
  --visibility private \
  --namespace project \
  --track "**/SPEC.md" \
  --track "docs/specs/**"

Use an existing shared sidecar:

skeeper init \
  --sidecar [email protected]:user/shared-specs.git \
  --namespace project \
  --track "**/SPEC.md"

Then edit specs and commit normally:

$EDITOR src/auth/SPEC.md
git add src/auth/service.go src/auth/SPEC.md
git commit -m "auth: design OAuth provider flow"

The pre-commit and pre-merge-commit hooks mirror specs and stage skeeper.lock. If a hook stages a new lock, review it and include it in the commit.

🛟 Failed Sync Recovery

Start with status. It prints the health summary and the next action:

skeeper status --paths

Use repair as the single recovery door for broken local state, stale bypasses, hook drift, missing sidecar objects, and interrupted transactions:

skeeper repair
skeeper status --check

When two clones have different docs and both sides should be preserved, use the union workflow:

skeeper sync
git add skeeper.lock
git commit -m "skeeper: sync docs"
git push

📖 CLI Reference

The public surface is intentionally small. status tells you what is wrong and what to run next; repair is the only public recovery door; Git hook and merge-driver plumbing runs through hidden skeeper internal commands.

🤖 CI Action

Use the same-repository Action to check Skeeper health in CI:

name: skeeper

on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: compozy/[email protected]
        with:
          args: |
            status
            --check
            --json
          ssh-private-key: ${{ secrets.SKEEPER_SSH_PRIVATE_KEY }}

Credential precedence:

1. ssh-private-key writes a temp key and sets GIT_SSH_COMMAND.
2. token configures HTTPS GitHub credentials.
3. Existing runner Git/SSH credentials are used when neither input is provided.

Secrets are masked before configuration. The wrapper downloads the released Skeeper binary for the action ref/tag and delegates the status check to the CLI.

🩺 Troubleshooting

SKEEPER_SKIP=1 was used

Run skeeper status, then skeeper sync, then skeeper status --check. The bypass journal remains visible until sync clears it.

Sidecar push was rejected

Run skeeper repair --check. If the failure is safe to repair automatically, run skeeper repair after fixing network/auth or sidecar contention. If the report names an ambiguous overwrite/delete decision, inspect the listed files manually and use skeeper sync after resolving it.

skeeper.lock conflicts during merge

Run skeeper repair to ensure hooks and merge-driver wiring are configured, then rerun the merge. Manual editing of scalar sidecar SHAs is unsupported; regenerate the lock through skeeper sync.

skeeper pull or skeeper restore is blocked by local managed files

Run skeeper status --paths or skeeper diff to inspect exact paths. Use skeeper sync when local-only docs or local deletes should be published. Use skeeper reconcile --ours or --theirs for conflicts. Use skeeper push --prune only when the local set is intentionally authoritative and remote-only docs without a trusted local deletion base should be pruned.

status --check reports a lock mismatch

The main commit and sidecar remote disagree. Run skeeper sync, include the updated skeeper.lock, and rerun skeeper status --check.

A namespace overlaps another namespace

Move shared files into exactly one namespace by adding exclude: entries. Skeeper does not use order-based precedence.

🚫 When Skeeper Is the Wrong Tool

• Repositories where specs already belong in the main diff and reviewers explicitly want them inline.
• Teams that need PR review on the spec content itself before merge — Skeeper mirrors after the main commit succeeds, by design.
• Repositories without a stable sidecar Git host: Skeeper fails the commit when the sidecar is unreachable (the audited SKEEPER_SKIP=1 bypass exists, but it is not a substitute for a working remote).
• Storing build artifacts, generated code, or large binaries. Default guardrails cap mutating plans at 100 files and 10 MiB on purpose.

🛠️ Development

mise install
bun install
make hooks-install
make verify

Common targets:

make fmt
make lint
make test
make build
make cover
make release-snapshot

Contributor guidance, commit conventions, and agent instructions live in CLAUDE.md and AGENTS.md.

📄 License

MIT