Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/fl03/shepherd

A plugin enabling an iterative, semi-automatic approach toward development
https://github.com/fl03/shepherd

claude claude-code claude-code-plugin

Last synced: 14 days ago
JSON representation

A plugin enabling an iterative, semi-automatic approach toward development

Awesome Lists containing this project

README 

          
# shepherd



[![GitHub License](https://img.shields.io/github/license/FL03/shepherd?style=for-the-badge&logo=github)](LICENSE)

[![GitHub Release](https://img.shields.io/github/v/release/FL03/shepherd?style=for-the-badge&logo=github)](https://github.com/FL03/shepherd/releases)



---



Welcome, the **shepherd** plugin is *an adaptive, sprint-by-sprint version-cycle conductor* designed for Claude Code. Shepherd turns a single session into a disciplined release engineer driving a closed six-agent flock through repeatable, audited sprint pipelines — with mechanical enforcement, SQLite-backed context, and zero passive waits.



```text

┌──────────────────────────────────────────────────────────────────────┐

│  /shepherd:plant     Seed authorship — Opus recommended (upstream)   │

│  /shepherd:start     One sprint end-to-end, then PAUSE               │

│                       --teammate    lane-execute (spawned sessions)  │

│  /shepherd:spawn     Root-shepherd + teammate-conductors             │

│                       --scope            │

│                       --parallel       sprint-level fanout        │

│                       --auto              alias: --scope patch       │

│  /shepherd:ctx       Inspect / refresh the per-project SQLite ctx    │

│  /shepherd:cleanup   Post-sprint worktree + lock cleanup             │

└──────────────────────────────────────────────────────────────────────┘

```



## Overview



Shepherd is an orchestration framework for long-running engineering work in Claude Code. It provides:



- A **closed six-agent flock** with fixed roles and dispatch contracts

- A **three-tier meta layer** that authors seeds, executes sprints, and coordinates teammate-conductors

- A **three-section pipeline** (INTRODUCTION → BODY → CLOSE) with wave-gated execution

- **Mechanical enforcement** via hooks that refuse dispatch drift before it happens

- A **per-project SQLite registry** that indexes symbols, issues, artifacts, and memories

- A **project-agnostic config** via `shepherd.toml` — branch topology, gates, paths, and skill wiring live in your repo, not in the framework



Shepherd is a plugin for Claude Code installed via the marketplace or a symlink. There is no build system — assets are markdown briefs, YAML frontmatter, and shell scripts.



---



## Architecture



### Three meta tiers



| Tier | Profile | Model | Adopted by | Role |

| :--: | :-----: | :---: | :--------: | :--: |

| 3 — root | `agents/shepherd.md` | inherit | Main chat under `/shepherd:spawn` | Engineer/critic dispatch, artifact materialization, dispute resolution, close-swarm coordination |

| 2 — conductor | `agents/conductor.md` | sonnet | Main chat under `/shepherd:start` (solo) or a spawned teammate session | Sprint/lane execution; dual solo/teammate mode |

| parallel — planter | `agents/planter.md` | inherit; opus (recommended) | Main chat under `/shepherd:plant`; mid-spawn delegated | Seed authorship, git custody, cleanup stewardship |



> **Planter model policy:** Fable 5 is superior; Opus (`claude-opus-4-8`) is the recommended default; Sonnet/Haiku are allowed but produce a degraded-seed advisory.



### The closed flock (six agents)



| Agent | Model | Dispatch | Role |

| :-------: | :-------: | :----------: | :------: |

| `@engineer` | Opus | Single, once per sprint | Phase 0 mesh + sprint plan authorship. Root-tier-exclusive under `/shepherd:spawn`. |

| `@critic` | Sonnet | Single, sequential gate | Adversarial review of plans, money-paths, merges. Root-tier-exclusive under `/shepherd:spawn`. |

| `@coder` | Sonnet | Parallel waves | Implementation; one per disjoint file scope |

| `@auditor` | Sonnet | Swarm of 3–5 | Read-only review at sprint close, split by concern |

| `@worker` | Sonnet | Single or parallel | Bounded execution: monitoring, research, ops |

| `@discovery` | Sonnet | Single or parallel | Read-only orientation, comprehension, synthesis |



The flock is **closed** — the contract changes only on a MAJOR version bump. Non-code work goes to `@worker`; research to `@discovery`. Adding agents outside these six is a framework violation.



### The pipeline



Every sprint runs three sections:



1. **INTRODUCTION** — Phase 0 mesh (ground-truth audit), plan authorship by `@engineer`, adversarial gate by `@critic`

2. **BODY** — coder waves with between-wave gates (`check`, `lint`, `format`); auditor swarm overlaps Wave 2 (Pattern B)

3. **CLOSE** — merge, tag, squash-to-main, carry-forward refresh, close report



Under `/shepherd:spawn`, the BODY is fanned out as **lanes** (vertical slices across waves), each owned by one teammate-conductor running via Agent Teams. Gate-free step fan-out compiles to Dynamic Workflows. Root stays active between waves — no passive waits.



---



## What it solves



Naive long-running Claude sessions suffer predictable failure modes. Shepherd addresses each mechanically:



| Problem | Shepherd's answer |

| :---------: | :-------------------: |

| **Tunnel vision** — conductor ignores the 200-issue ledger underneath | Phase 0 mesh enumerates ALL open issues, surfaces CRITICAL/HIGH outside the current milestone as drift risks |

| **Duplication** — types and helpers re-invented because nobody grepped first | `[DO-NOT-DUPLICATE]` grep gate in every coder brief; `must-be-zero` violations halt the lane |

| **Silent scope drift** — sprints add features that weren't seeded | Every brief is issued-anchored to the seed; auditor's `completeness` concern fails any lane that drifted |

| **Audit theater** — "passes review" because the reviewer is the same context that wrote it | Read-only `@auditor` swarm (3–5 agents, split by concern) runs in parallel, dispatched from root |

| **Wrapper bloat** — hollow structs added for structure's sake | Wrapper-grep gate at sprint close; `SUBTRACT-DON'T-ADD` doctrine requires net-negative LOC/dep/abstraction |

| **Release malpractice** — squash-merging unsigned, untested, un-tagged commits | Conductor drives the full squash-to-main pipeline with gate sequencing and signed commits |

| **Passive dispatch boundary waits** — root stalls after spawning teammates | Coordinate-active-drive doctrine + `coordinate_drive_guard.sh` hook mechanically blocks premature halt |

| **Context bleed between coders** — parallel coders see each other's drift | Each coder scoped to a disjoint file set; anti-duplication greps prevent cross-scope re-invention |



---



## Key features



### Phase 0 mesh



Every sprint opens with a structured ground-truth audit: open issues + PRs, recent Sentry/Supabase/Fly state, carry-forwards from prior sprints. The engineer can't skip it; auditors verify the mesh was complete.



### SQLite context registry



`/shepherd:ctx` manages a per-project SQLite database at `.shepherd/root.db` (or `.artifacts/root.db` for legacy projects). It indexes code symbols, GitHub issues/PRs/releases, artifact files, project memories, flock profiles, lock history, and the event log.



```bash

shctx init                   # scaffold .shepherd/, create root.db

shctx refresh --scope=all    # populate caches

shctx status                 # verify

shctx style init --all       # scaffold per-language code-style files

```



### Per-language style files



Project-local code-style overrides live at `.shepherd/styles/.md` (rust, python, typescript, go, shell, sql). Tracked in git. The conductor injects the matching style file into every coder brief whose file scope touches that language.



```bash

shctx style init rust        # scaffold from bundled defaults

shctx style show rust        # print current style

shctx style edit rust        # open in $EDITOR

```



### Mechanical enforcement hooks



Shepherd ships a full hook suite wired via `hooks/hooks.json`:



- **`dispatch_guard.sh`** — PreToolUse guard that hard-refuses missing/wrong `subagent_type`, off-flock impersonation, and wrong-tier `@engineer`/`@critic` dispatch from teammates

- **`bash_guard.sh`** — blocks workflow→teammate dispatch inversion and backgrounded cargo gates

- **`coordinate_drive_guard.sh`** — Stop hook that blocks premature root halt while teammates are idle or lead mail is unread

- **`close_finalize_check.sh`** — validates close-finalize preconditions (close report committed, sprint branch still on origin) before the stop event fires

- **`_lib.sh`** — shared resolution: `SHEPHERD_WORKDIR` override → `SHCTX_ROOT_OVERRIDE` → pre-existing `.shepherd/` → pre-existing `.artifacts/` → default `.shepherd/`



### Scope-scaled workload



`/shepherd:spawn --scope ` scales workload per a four-tier roadmap. `--scope patch` runs sequential sprints to patch completion; `--parallel ` fans out N disjoint sprints across git worktrees. `--auto` aliases `--scope patch`.



### Carry-forward refresh



The `completeness` auditor diffs the GitHub issue ledger against the sprint's seed at sprint close and files chronic items at ≥ 2 patch crossings — nothing falls through permanently.



### Doctrines



Framework-intrinsic behavioral rules live in `skills/shepherd/doctrines/`. These are not prose guidance — each doctrine is paired with a mechanism (hook, guard, or halt code) in the invariant-enforcement matrix. Current doctrines include: `subtract-dont-add`, `wrapper-must-earn`, `dispatch-tier-separation`, `coordinate-active-drive`, `hotfix-dispatch`, `workflow-patterns`, `sqlite-canonical-state`, `brief-cache-discipline`, and 20+ others.



---



## Install



### From the Claude Code marketplace (recommended)



```text

/plugin marketplace add fl03/shepherd

/plugin install shepherd@fl03

```



Registers the self-hosted marketplace manifest and pulls shepherd as a managed plugin. Updates via `/plugin update shepherd@fl03`.



### Personal install via symlink



```bash

git clone https://github.com/FL03/shepherd.git ~/src/FL03/shepherd

ln -s ~/src/FL03/shepherd ~/.claude/plugins/shepherd

```



### Per-project pin



```bash

mkdir -p .claude-plugin

ln -s /path/to/FL03/shepherd .claude-plugin/shepherd

```



---



## Configure



Create `.claude/shepherd.toml` at the project root. Shepherd surfaces a warning at every invocation until one exists.



Config search order (first found wins):



```

.claude/shepherd.toml         ← project-pinned, checked into the repo

.claude/shepherd.local.toml   ← project-pinned, gitignored (operator overrides)

$XDG_CONFIG_HOME/shepherd.toml ← user-global default

```



Minimal example:



```toml

[project]

name        = "my-project"

language    = "rust"          # rust | python | typescript | go | mixed



[branching]

patch_branch_pattern  = "v{X}.{Y}.{Z}"

sprint_branch_pattern = "v{X}.{Y}.{Z}-dev.{N}"

sprints_per_patch     = 10

main_branch           = "main"



[gates]

check  = "cargo check --workspace"

lint   = "cargo clippy --workspace -- -D warnings"

format = "cargo fmt --all"



[paths]

plans   = ".shepherd/plans"

reports = ".shepherd/reports"

docs    = ".shepherd/docs"

ctx     = ".shepherd/ctx"



[skills]

mandatory  = ["code-style"]

by_domain  = { rust = ["rust"], wasm = ["webassembly"] }

```



See [`docs/configuration.md`](docs/configuration.md) for the full schema including `[gates.extra]`, `[spawn]`, `[release]`, and the language matrix.



A working example for a real Rust/Polymarket project lives at [`examples/axiom/shepherd.toml`](examples/axiom/shepherd.toml).



---



## Usage



### First-time setup



1. Create `shepherd.toml` (see above).

2. Run `/shepherd:ctx` to initialize the SQLite registry.

3. Optionally author a patch-arc seed at `.shepherd/plans/v{X}.{Y}.{Z}.seed.md` describing the patch's theme.

4. Run `/shepherd:plant` (Opus recommended — Fable 5 superior; Sonnet/Haiku allowed with degraded-seed advisory) to author the dev.0 sprint seed.

5. Switch to Sonnet and run `/shepherd:start` for your first sprint.



### Common commands



```bash

# Author seeds for upcoming sprints

/shepherd:plant

/shepherd:plant dev.5

/shepherd:plant arc



# Run a single sprint end-to-end, then pause for operator sign-off

/shepherd:start



# Spawn teammate-conductors (full lane-per-conductor fanout)

/shepherd:spawn



# Sequential autopilot — fresh context per sprint, through patch completion

/shepherd:spawn --auto



# Fan out N disjoint sprints in parallel across git worktrees

/shepherd:spawn --parallel 3



# Inspect/refresh the context registry

/shepherd:ctx



# Clean up post-sprint worktrees and lock files

/shepherd:cleanup

```



---



## Integration with local skills



Shepherd is designed to compose with your locally developed skills, not replace them:



- **`code-style`** — injected into every coder brief by default. Provides your personal per-language preferences (idioms, comment discipline, naming conventions). Shepherd provides orchestration; `code-style` provides the per-keystroke voice.

- **Domain skills** (`rust`, `webassembly`, `finance`, `supabase`, etc.) — wired into the Required-Skills Matrix via `[skills.by_domain]` in `shepherd.toml`. Attached automatically when the coder's file scope matches.

- **`superpowers:brainstorming` + `superpowers:writing-plans`** — loaded by `@engineer` from inside its own dispatch. Plan quality depends on these.



See [`docs/integration.md`](docs/integration.md) for the full integration model including MCP bindings, Sentry/Supabase/Fly state injection, and custom doctrine authorship.



---



## File map



| Path | Purpose |

| :------: | :---------: |

| `.claude-plugin/plugin.json` | Plugin manifest |

| `.claude-plugin/marketplace.json` | Self-hosted marketplace entry |

| `agents/{engineer,critic,coder,auditor,worker,discovery}.md` | Closed flock — full system prompts per lane |

| `agents/{shepherd,conductor,planter}.md` | Three meta-orchestrators |

| `commands/{plant,start,spawn,ctx,cleanup}.md` | Active slash-command entry points |

| `skills/shepherd/SKILL.md` | Conductor quick reference (loaded by every `/shepherd:*` invocation) |

| `skills/shepherd/doctrines/*.md` | Framework-intrinsic behavioral rules |

| `skills/shepherd/references/` | Branching model, seed template, agent-brief templates, grading rubric |

| `skills/context/SKILL.md` | `shctx` runtime entry point |

| `skills/context/schema/` | SQL migrations + views for the SQLite registry |

| `skills/context/scripts/` | `shctx` + `cmd_*` implementations (bash) |

| `skills/context/styles/.md` | Bundled per-language code-style defaults |

| `hooks/hooks.json` | Event registrations wiring Claude Code lifecycle → hook scripts |

| `hooks/scripts/` | Hook implementations (sourced from `_lib.sh`) |

| `hooks/tests/` | Smoke harness — `bash hooks/tests/run.sh` |

| `docs/{configuration,integration,customization}.md` | Operator-facing documentation |

| `examples/axiom/` | Working Rust/Polymarket bindings (config + CLAUDE.md snippet) |

| `examples/minimal/` | Stripped-down starter config |



---



## Versioning



Shepherd follows semver:



- **MAJOR** — closed-flock contract changes (adding/removing a lane, flipping critic to parallel)

- **MINOR** — new commands, doctrines, or config keys (backward-compatible)

- **PATCH** — dispatch logic, doctrine, or brief-template fixes



Version sources of truth that must move together: `plugin.json`, `marketplace.json`, `skills/shepherd/SKILL.md` frontmatter, `skills/context/SKILL.md` frontmatter, `README.md` header, `CHANGELOG.md`. `shctx release` automates the five non-CHANGELOG files.



Current version: **6.1.1**. See [`CHANGELOG.md`](CHANGELOG.md) for the per-version history.



---



## License



Apache-2.0. See `LICENSE` at the repo root.