{"id":50044306,"url":"https://github.com/fl03/shepherd","last_synced_at":"2026-06-10T04:00:58.977Z","repository":{"id":357263389,"uuid":"1236164309","full_name":"FL03/shepherd","owner":"FL03","description":"A plugin enabling an iterative, semi-automatic approach toward development","archived":false,"fork":false,"pushed_at":"2026-06-04T20:35:43.000Z","size":1101,"stargazers_count":0,"open_issues_count":39,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T22:05:06.951Z","etag":null,"topics":["claude","claude-code","claude-code-plugin"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FL03.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["FL03"],"open_collective":"pzzld"}},"created_at":"2026-05-12T02:18:34.000Z","updated_at":"2026-06-04T20:35:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/FL03/shepherd","commit_stats":null,"previous_names":["fl03/shepherd"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/FL03/shepherd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FL03%2Fshepherd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FL03%2Fshepherd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FL03%2Fshepherd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FL03%2Fshepherd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FL03","download_url":"https://codeload.github.com/FL03/shepherd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FL03%2Fshepherd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34136112,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","claude-code-plugin"],"created_at":"2026-05-21T05:09:53.995Z","updated_at":"2026-06-10T04:00:58.955Z","avatar_url":"https://github.com/FL03.png","language":"Shell","funding_links":["https://github.com/sponsors/FL03","https://opencollective.com/pzzld"],"categories":[],"sub_categories":[],"readme":"# shepherd\n\n[![GitHub License](https://img.shields.io/github/license/FL03/shepherd?style=for-the-badge\u0026logo=github)](LICENSE)\n[![GitHub Release](https://img.shields.io/github/v/release/FL03/shepherd?style=for-the-badge\u0026logo=github)](https://github.com/FL03/shepherd/releases)\n\n---\n\nWelcome, 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.\n\n```text\n┌──────────────────────────────────────────────────────────────────────┐\n│  /shepherd:plant     Seed authorship — Opus recommended (upstream)   │\n│  /shepherd:start     One sprint end-to-end, then PAUSE               │\n│                       --teammate    lane-execute (spawned sessions)  │\n│  /shepherd:spawn     Root-shepherd + teammate-conductors             │\n│                       --scope \u003csprint|patch|minor|version\u003e           │\n│                       --parallel \u003cN\u003e      sprint-level fanout        │\n│                       --auto              alias: --scope patch       │\n│  /shepherd:ctx       Inspect / refresh the per-project SQLite ctx    │\n│  /shepherd:cleanup   Post-sprint worktree + lock cleanup             │\n└──────────────────────────────────────────────────────────────────────┘\n```\n\n## Overview\n\nShepherd is an orchestration framework for long-running engineering work in Claude Code. It provides:\n\n- A **closed six-agent flock** with fixed roles and dispatch contracts\n- A **three-tier meta layer** that authors seeds, executes sprints, and coordinates teammate-conductors\n- A **three-section pipeline** (INTRODUCTION → BODY → CLOSE) with wave-gated execution\n- **Mechanical enforcement** via hooks that refuse dispatch drift before it happens\n- A **per-project SQLite registry** that indexes symbols, issues, artifacts, and memories\n- A **project-agnostic config** via `shepherd.toml` — branch topology, gates, paths, and skill wiring live in your repo, not in the framework\n\nShepherd 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.\n\n---\n\n## Architecture\n\n### Three meta tiers\n\n| Tier | Profile | Model | Adopted by | Role |\n| :--: | :-----: | :---: | :--------: | :--: |\n| 3 — root | `agents/shepherd.md` | inherit | Main chat under `/shepherd:spawn` | Engineer/critic dispatch, artifact materialization, dispute resolution, close-swarm coordination |\n| 2 — conductor | `agents/conductor.md` | sonnet | Main chat under `/shepherd:start` (solo) or a spawned teammate session | Sprint/lane execution; dual solo/teammate mode |\n| parallel — planter | `agents/planter.md` | inherit; opus (recommended) | Main chat under `/shepherd:plant`; mid-spawn delegated | Seed authorship, git custody, cleanup stewardship |\n\n\u003e **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.\n\n### The closed flock (six agents)\n\n| Agent | Model | Dispatch | Role |\n| :-------: | :-------: | :----------: | :------: |\n| `@engineer` | Opus | Single, once per sprint | Phase 0 mesh + sprint plan authorship. Root-tier-exclusive under `/shepherd:spawn`. |\n| `@critic` | Sonnet | Single, sequential gate | Adversarial review of plans, money-paths, merges. Root-tier-exclusive under `/shepherd:spawn`. |\n| `@coder` | Sonnet | Parallel waves | Implementation; one per disjoint file scope |\n| `@auditor` | Sonnet | Swarm of 3–5 | Read-only review at sprint close, split by concern |\n| `@worker` | Sonnet | Single or parallel | Bounded execution: monitoring, research, ops |\n| `@discovery` | Sonnet | Single or parallel | Read-only orientation, comprehension, synthesis |\n\nThe 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.\n\n### The pipeline\n\nEvery sprint runs three sections:\n\n1. **INTRODUCTION** — Phase 0 mesh (ground-truth audit), plan authorship by `@engineer`, adversarial gate by `@critic`\n2. **BODY** — coder waves with between-wave gates (`check`, `lint`, `format`); auditor swarm overlaps Wave 2 (Pattern B)\n3. **CLOSE** — merge, tag, squash-to-main, carry-forward refresh, close report\n\nUnder `/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.\n\n---\n\n## What it solves\n\nNaive long-running Claude sessions suffer predictable failure modes. Shepherd addresses each mechanically:\n\n| Problem | Shepherd's answer |\n| :---------: | :-------------------: |\n| **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 |\n| **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 |\n| **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 |\n| **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 |\n| **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 |\n| **Release malpractice** — squash-merging unsigned, untested, un-tagged commits | Conductor drives the full squash-to-main pipeline with gate sequencing and signed commits |\n| **Passive dispatch boundary waits** — root stalls after spawning teammates | Coordinate-active-drive doctrine + `coordinate_drive_guard.sh` hook mechanically blocks premature halt |\n| **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 |\n\n---\n\n## Key features\n\n### Phase 0 mesh\n\nEvery 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.\n\n### SQLite context registry\n\n`/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.\n\n```bash\nshctx init                   # scaffold .shepherd/, create root.db\nshctx refresh --scope=all    # populate caches\nshctx status                 # verify\nshctx style init --all       # scaffold per-language code-style files\n```\n\n### Per-language style files\n\nProject-local code-style overrides live at `.shepherd/styles/\u003clang\u003e.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.\n\n```bash\nshctx style init rust        # scaffold from bundled defaults\nshctx style show rust        # print current style\nshctx style edit rust        # open in $EDITOR\n```\n\n### Mechanical enforcement hooks\n\nShepherd ships a full hook suite wired via `hooks/hooks.json`:\n\n- **`dispatch_guard.sh`** — PreToolUse guard that hard-refuses missing/wrong `subagent_type`, off-flock impersonation, and wrong-tier `@engineer`/`@critic` dispatch from teammates\n- **`bash_guard.sh`** — blocks workflow→teammate dispatch inversion and backgrounded cargo gates\n- **`coordinate_drive_guard.sh`** — Stop hook that blocks premature root halt while teammates are idle or lead mail is unread\n- **`close_finalize_check.sh`** — validates close-finalize preconditions (close report committed, sprint branch still on origin) before the stop event fires\n- **`_lib.sh`** — shared resolution: `SHEPHERD_WORKDIR` override → `SHCTX_ROOT_OVERRIDE` → pre-existing `.shepherd/` → pre-existing `.artifacts/` → default `.shepherd/`\n\n### Scope-scaled workload\n\n`/shepherd:spawn --scope \u003csprint|patch|minor|version\u003e` scales workload per a four-tier roadmap. `--scope patch` runs sequential sprints to patch completion; `--parallel \u003cN\u003e` fans out N disjoint sprints across git worktrees. `--auto` aliases `--scope patch`.\n\n### Carry-forward refresh\n\nThe `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.\n\n### Doctrines\n\nFramework-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.\n\n---\n\n## Install\n\n### From the Claude Code marketplace (recommended)\n\n```text\n/plugin marketplace add fl03/shepherd\n/plugin install shepherd@fl03\n```\n\nRegisters the self-hosted marketplace manifest and pulls shepherd as a managed plugin. Updates via `/plugin update shepherd@fl03`.\n\n### Personal install via symlink\n\n```bash\ngit clone https://github.com/FL03/shepherd.git ~/src/FL03/shepherd\nln -s ~/src/FL03/shepherd ~/.claude/plugins/shepherd\n```\n\n### Per-project pin\n\n```bash\nmkdir -p .claude-plugin\nln -s /path/to/FL03/shepherd .claude-plugin/shepherd\n```\n\n---\n\n## Configure\n\nCreate `.claude/shepherd.toml` at the project root. Shepherd surfaces a warning at every invocation until one exists.\n\nConfig search order (first found wins):\n\n```\n.claude/shepherd.toml         ← project-pinned, checked into the repo\n.claude/shepherd.local.toml   ← project-pinned, gitignored (operator overrides)\n$XDG_CONFIG_HOME/shepherd.toml ← user-global default\n```\n\nMinimal example:\n\n```toml\n[project]\nname        = \"my-project\"\nlanguage    = \"rust\"          # rust | python | typescript | go | mixed\n\n[branching]\npatch_branch_pattern  = \"v{X}.{Y}.{Z}\"\nsprint_branch_pattern = \"v{X}.{Y}.{Z}-dev.{N}\"\nsprints_per_patch     = 10\nmain_branch           = \"main\"\n\n[gates]\ncheck  = \"cargo check --workspace\"\nlint   = \"cargo clippy --workspace -- -D warnings\"\nformat = \"cargo fmt --all\"\n\n[paths]\nplans   = \".shepherd/plans\"\nreports = \".shepherd/reports\"\ndocs    = \".shepherd/docs\"\nctx     = \".shepherd/ctx\"\n\n[skills]\nmandatory  = [\"code-style\"]\nby_domain  = { rust = [\"rust\"], wasm = [\"webassembly\"] }\n```\n\nSee [`docs/configuration.md`](docs/configuration.md) for the full schema including `[gates.extra]`, `[spawn]`, `[release]`, and the language matrix.\n\nA working example for a real Rust/Polymarket project lives at [`examples/axiom/shepherd.toml`](examples/axiom/shepherd.toml).\n\n---\n\n## Usage\n\n### First-time setup\n\n1. Create `shepherd.toml` (see above).\n2. Run `/shepherd:ctx` to initialize the SQLite registry.\n3. Optionally author a patch-arc seed at `.shepherd/plans/v{X}.{Y}.{Z}.seed.md` describing the patch's theme.\n4. Run `/shepherd:plant` (Opus recommended — Fable 5 superior; Sonnet/Haiku allowed with degraded-seed advisory) to author the dev.0 sprint seed.\n5. Switch to Sonnet and run `/shepherd:start` for your first sprint.\n\n### Common commands\n\n```bash\n# Author seeds for upcoming sprints\n/shepherd:plant\n/shepherd:plant dev.5\n/shepherd:plant arc\n\n# Run a single sprint end-to-end, then pause for operator sign-off\n/shepherd:start\n\n# Spawn teammate-conductors (full lane-per-conductor fanout)\n/shepherd:spawn\n\n# Sequential autopilot — fresh context per sprint, through patch completion\n/shepherd:spawn --auto\n\n# Fan out N disjoint sprints in parallel across git worktrees\n/shepherd:spawn --parallel 3\n\n# Inspect/refresh the context registry\n/shepherd:ctx\n\n# Clean up post-sprint worktrees and lock files\n/shepherd:cleanup\n```\n\n---\n\n## Integration with local skills\n\nShepherd is designed to compose with your locally developed skills, not replace them:\n\n- **`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.\n- **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.\n- **`superpowers:brainstorming` + `superpowers:writing-plans`** — loaded by `@engineer` from inside its own dispatch. Plan quality depends on these.\n\nSee [`docs/integration.md`](docs/integration.md) for the full integration model including MCP bindings, Sentry/Supabase/Fly state injection, and custom doctrine authorship.\n\n---\n\n## File map\n\n| Path | Purpose |\n| :------: | :---------: |\n| `.claude-plugin/plugin.json` | Plugin manifest |\n| `.claude-plugin/marketplace.json` | Self-hosted marketplace entry |\n| `agents/{engineer,critic,coder,auditor,worker,discovery}.md` | Closed flock — full system prompts per lane |\n| `agents/{shepherd,conductor,planter}.md` | Three meta-orchestrators |\n| `commands/{plant,start,spawn,ctx,cleanup}.md` | Active slash-command entry points |\n| `skills/shepherd/SKILL.md` | Conductor quick reference (loaded by every `/shepherd:*` invocation) |\n| `skills/shepherd/doctrines/*.md` | Framework-intrinsic behavioral rules |\n| `skills/shepherd/references/` | Branching model, seed template, agent-brief templates, grading rubric |\n| `skills/context/SKILL.md` | `shctx` runtime entry point |\n| `skills/context/schema/` | SQL migrations + views for the SQLite registry |\n| `skills/context/scripts/` | `shctx` + `cmd_*` implementations (bash) |\n| `skills/context/styles/\u003clang\u003e.md` | Bundled per-language code-style defaults |\n| `hooks/hooks.json` | Event registrations wiring Claude Code lifecycle → hook scripts |\n| `hooks/scripts/` | Hook implementations (sourced from `_lib.sh`) |\n| `hooks/tests/` | Smoke harness — `bash hooks/tests/run.sh` |\n| `docs/{configuration,integration,customization}.md` | Operator-facing documentation |\n| `examples/axiom/` | Working Rust/Polymarket bindings (config + CLAUDE.md snippet) |\n| `examples/minimal/` | Stripped-down starter config |\n\n---\n\n## Versioning\n\nShepherd follows semver:\n\n- **MAJOR** — closed-flock contract changes (adding/removing a lane, flipping critic to parallel)\n- **MINOR** — new commands, doctrines, or config keys (backward-compatible)\n- **PATCH** — dispatch logic, doctrine, or brief-template fixes\n\nVersion 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.\n\nCurrent version: **6.1.1**. See [`CHANGELOG.md`](CHANGELOG.md) for the per-version history.\n\n---\n\n## License\n\nApache-2.0. See `LICENSE` at the repo root.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffl03%2Fshepherd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffl03%2Fshepherd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffl03%2Fshepherd/lists"}