promptherder

Promptherder

Go CLI that manages AI agent configuration per repo. .promptherder/ is the source of truth for each repository's agent rules, skills, and workflows.

How It Works

Sources                          Agent targets (local)
┌──────────────┐
│ herds (GitHub)│──┐
└──────────────┘  │
                  ├──→  .agents/        (Antigravity)
┌──────────────┐  ├──→  .github/        (Copilot)
│ repo-local   │──┘
│ (.promptherder/agent/)
└──────────────┘

• Herds provide shared skills/rules across repos (pulled from GitHub)
• Repo-local files in .promptherder/agent/ add per-project skills, rules, or overrides
• hard-rules.md in .promptherder/ contains always-on rules specific to this repo
• promptherder merges everything and fans out to each agent target
• .promptherder/manifest.json tracks what files promptherder owns

Commands

# Install a herd
promptherder pull https://github.com/shermanhuman/compound-v
promptherder pull https://github.com/shermanhuman/oh

# Sync to all targets (run after every pull)
promptherder

# Preview without writing
promptherder -dry-run

# Sync one target only
promptherder copilot
promptherder antigravity

Herd Structure

A herd is a GitHub repo with herd.json and content in rules/, skills/, workflows/:

my-herd/
├── herd.json        # {"name": "my-herd", "version": "0.1.0"}
├── rules/
│   └── my-rule.md
├── skills/
│   └── my-skill/
│       └── SKILL.md
└── workflows/
    └── plan.md

Only rules/, skills/, and workflows/ are synced. Everything else is metadata.

Key Facts

• pull downloads but does not sync — always run bare promptherder after
• Two herds providing the same file path = conflict error
• Files listed in manifest's generated array (e.g., stack.md) are never overwritten
• Skills can have target-specific variants: COPILOT.md or ANTIGRAVITY.md override SKILL.md
• No git binary required — pull uses GitHub API tarball