{"id":51867279,"url":"https://github.com/apify/shepherd","last_synced_at":"2026-07-24T18:00:57.146Z","repository":{"id":371294192,"uuid":"1299057802","full_name":"apify/shepherd","owner":"apify","description":"Shepherd is a Claude Code plugin for running coding work through a controlled, human-gated loop","archived":false,"fork":false,"pushed_at":"2026-07-14T09:53:37.000Z","size":355,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-14T11:31:50.315Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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}},"created_at":"2026-07-13T08:38:37.000Z","updated_at":"2026-07-14T09:53:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/apify/shepherd","commit_stats":null,"previous_names":["apify/shepherd"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/apify/shepherd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fshepherd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fshepherd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fshepherd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fshepherd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apify","download_url":"https://codeload.github.com/apify/shepherd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apify%2Fshepherd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35850518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-24T02:00:07.870Z","response_time":62,"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":[],"created_at":"2026-07-24T18:00:56.336Z","updated_at":"2026-07-24T18:00:57.129Z","avatar_url":"https://github.com/apify.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shepherd\n\nshepherd is a Claude Code plugin for running coding work through a controlled,\nhuman-gated loop. `/shepherd \u003ctask\u003e` separates product triage, request verification,\ndesign, success criteria, implementation, review, tests, fulfillment, and create-PR\napproval into durable files under `.shepherd/`.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/shepherd-overview.svg\" width=\"920\"\n       alt=\"shepherd overview — the orchestrator routes, subagents judge, and files are the only handoff; the run flows from /shepherd \u003ctask\u003e through triage, verify, design, and human iteration to the design gate, then an implement/review loop, final reviewers, and a fulfillment check, ending at a create-PR confirm before commit.\"\u003e\n\u003c/p\u003e\n\nThe core principle: **the orchestrator routes; subagents judge; files are the only\nhandoff.** Every judgment — the claim ledger, the design, the success criteria, each\nreview, the fulfillment check — is a subagent writing one file with a narrow read set.\nThe orchestrator never authors a judgment file; it dispatches, shows you the results,\nand records your feedback verbatim.\n\nThree properties matter most:\n\n- **The design is shaped with you.** After a cheap triage and an always-on fact check,\n  subagents draft a product-first design and independent success criteria. shepherd then\n  iterates with you in chat — one question at a time, each with a recommended answer,\n  product questions first. Your answers go verbatim into a feedback file and the\n  architect revises its own draft in a cheap revision pass. The design gate becomes a\n  quick confirmation of something you already shaped.\n- **Judgments are blind.** The architect never sees the success criteria; the criteria\n  author never sees the proposed solution; reviewers get pasted design + criteria + diff\n  + tests plus read access to the repository itself — never the implementer's claims or\n  each other's findings. Blindness applies to judgments, never to ground truth.\n- **\"Done\" is checked, not claimed.** Before the create-PR confirm, a fulfillment\n  subagent judges the diff and tests against the success criteria written before the\n  solution existed — `MET | NOT MET` per criterion, with evidence.\n\n## Flow\n\nThe diagram above is the map; the block below is the same run as a quick text\nreference, and the collapsible holds a Mermaid version for editing.\n\n\u003cdetails\u003e\n\u003csummary\u003eMermaid flow diagram\u003c/summary\u003e\n\n```mermaid\nflowchart TD\n    Start[\"/shepherd \u003ctask\u003e\"] --\u003e Triage[\"Triage (orchestrator)\u003cbr/\u003ePROCEED / DEFER / DECLINE\"]\n    Triage --\u003e|PROCEED| Verify[\"Verify (subagent, always)\u003cbr/\u003eclaim ledger\"]\n    Triage --\u003e|DEFER or DECLINE| Stop[\"Stop with recommendation\"]\n    Verify --\u003e|claims hold| Draft[\"Architect drafts 2-design.md\u003cbr/\u003ethen success criteria (blind)\"]\n    Verify --\u003e|stale / already fixed| Stop\n    Draft --\u003e Iterate[\"Iterate with the human\u003cbr/\u003efeedback file + revision passes\"]\n    Iterate --\u003e Gate{\"Design gate\u003cbr/\u003eapprove design + criteria + panel\"}\n    Gate --\u003e|approved| ReviewOnly{\"Review-only task?\"}\n    Gate --\u003e|revise| Iterate\n    ReviewOnly --\u003e|yes| ExistingDiff[\"Build diff from branch/PR\"]\n    ExistingDiff --\u003e ReviewPanel[\"Run approved reviewers\"]\n    ReviewPanel --\u003e Findings[\"Report findings\"]\n    ReviewOnly --\u003e|no| Implement[\"Implement approved design\"]\n    Implement --\u003e Oracle[\"Run oracle commands\"]\n    Oracle --\u003e Reviewers[\"Run blind reviewers\"]\n    Reviewers --\u003e Clean{\"Oracle green,\u003cbr/\u003eall findings fixed?\"}\n    Clean --\u003e|no| Implement\n    Clean --\u003e|yes| FinalReview[\"Final reviewers (if configured)\"]\n    FinalReview --\u003e|findings| Implement\n    FinalReview --\u003e|clean| Fulfillment[\"Fulfillment check\u003cbr/\u003ecriteria vs reality\"]\n    Fulfillment --\u003e|NOT MET| Implement\n    Fulfillment --\u003e|MET| CreatePrConfirm{\"Create-PR confirm\u003cbr/\u003ecommit \u0026 open PR?\"}\n    CreatePrConfirm --\u003e|yes| Finish[\"Commit / push / PR\"]\n    CreatePrConfirm --\u003e|no| Hold[\"Wait\"]\n```\n\n\u003c/details\u003e\n\n```text\n/shepherd \u003ctask\u003e\n  triage (orchestrator product screen; no gate, stops only on DEFER/DECLINE)\n  verify (subagent, always)      -\u003e claim ledger; stops if the request is stale\n  architect + success criteria   -\u003e blind drafts\n  iterate with the human         -\u003e feedback file + revision passes\n                                 -\u003e DESIGN GATE: approve design + criteria + panel\n  implement -\u003e oracle -\u003e blind reviewers -\u003e final reviewers\n                                    (loop until every finding is fixed)\n  fulfillment (subagent)         -\u003e every criterion MET, or reopen / ask\n  create-PR confirm (plain chat) -\u003e commit / PR\n```\n\nThere are two human gates: the **design gate** before source edits and the **create-PR\nconfirm** before any git write. Triage is deliberately cheap and continues unless it\nrecommends `DEFER` or `DECLINE`.\n\nAt the design gate, shepherd writes `_panel.json` so each run gets the right reviewer\nset for its risk: a small bug can use a small panel, while a core or public-contract\nchange can use the full roster. The panel also pins the model for each stage — every\n`auto` is resolved to a concrete model by role and complexity tier and shown to you to\nbump up or down before approving. Approval covers the design, the success criteria, and\nthe panel together.\n\nConvergence is zero-findings: every finding gets fixed, whatever its severity — nits too;\nnothing is skipped and nothing waits on your nudge. You only hear about open findings if\nthe iteration limits run out first. No PR happens without fulfillment: every criterion\n`MET`, or you explicitly accept the recorded exception.\n\nOn web/mobile/remote sessions the human sees only the chat stream, so shepherd surfaces\neverything into the conversation: the full `2-design.md` and `3-success-criteria.md` are\npasted or rendered as an Artifact (not just linked on disk), and run progress shows as a\none-line status at each phase transition — never assume the human can open `.shepherd/`\nfiles or type a slash-command.\n\nReview-only work is first-class. For a task like \"review PR/branch X\", shepherd runs\ntriage, verify, design (the review scope), the approved review panel against the\nexisting diff, and a findings summary. It only enters the implementation loop if you ask\nit to fix those findings.\n\n## Commands\n\n- `/shepherd \u003ctask\u003e` starts a new run.\n- `/shepherd` resumes the run recorded in `.shepherd/_state.json`.\n- `/shepherd-approve-design` is the human-only command for approving\n  `.shepherd/2-design.md`, `.shepherd/3-success-criteria.md`, and `.shepherd/_panel.json`\n  (records the panel and writes the marker).\n- `/shepherd-approve-create-pr` is the human-only fallback for recording approval\n  before commit, push, and PR creation.\n\nThe design gate is generic and portable: shepherd presents the design, criteria, and\npanel and waits for one of two human-driven outcomes. **Approve** — a chat \"yes\" or\n`/shepherd-approve-design` — writes `_design.approved` and proceeds. **Revise** — any\nchange request — goes back to the design iteration (feedback file + revision passes) and\nre-presents, iterating until you approve. For any agent that has a plan mode (Claude\nCode, Cursor, Codex, …), `plan_mode_gate: true` (the default) presents this through plan\nmode as an adapter: accepting the plan is Approve, rejecting or editing it is Revise; if\nthe plan tool errors or is unavailable (remote, headless, web sessions) it falls back to\nthe chat gate. The agent never self-approves — a plan-tool error or a \"continue\" message\nis never approval. Creating the PR uses a chat yes/no or `/shepherd-approve-create-pr`.\nThe on-disk `_design.approved` / `_create_pr.approved` markers are the only approval\nsignals.\n\n## Install\n\n```text\n/plugin marketplace add apify/shepherd\n/plugin install shepherd@shepherd\n```\n\nFor local development, load the plugin directory directly:\n\n```bash\nclaude --plugin-dir /path/to/shepherd/.claude\n```\n\nOn claude.ai/code, attach this repo. In another repo, copy `.claude/skills/` or install\nthe plugin. Use the commands without a `shepherd:` prefix.\n\n### Prompt reads during a run\n\nDuring a run, shepherd may read engine files under `.claude/skills/_vendored/` as\ninstruction text. These read-only prompts are expected.\n\nIf you copied `.claude/skills/` into your repo or attached this repo, allowlist the\nprompt reads in `.claude/settings.json`:\n\n```json\n{ \"permissions\": { \"allow\": [\"Read(.claude/skills/_vendored/**)\", \"Read(.claude/skills/shepherd/**)\"] } }\n```\n\nWhen installed as a plugin, the files live under the plugin path, so that glob will not\nmatch. Approve the prompts once in that environment.\n\n## Files\n\nRun data lives in `.shepherd/`; plugin tooling lives in `.claude/skills/`. Each run\nwrites a `.shepherd/.gitignore` that keeps everything ignored except `config.json` and\n`registry.json` — committable, shareable team config (shepherd itself never commits\n`.shepherd/` paths); run evidence is summarized in the PR body instead.\n\nHuman-facing files:\n\n- `.shepherd/1-triage.md`: product decision, complexity, approach sketch (orchestrator).\n- `.shepherd/2-design.md`: product-first design with open questions (architect subagent).\n- `.shepherd/3-success-criteria.md`: testable \"done\", written blind to the solution\n  (success-criteria subagent).\n\nInternal files:\n\n- `.shepherd/_user_request.md`: raw task text.\n- `.shepherd/_request_fact_check.md`: authoritative claim ledger (verify subagent).\n- `.shepherd/_codebase_map.md` (optional): explorer output for medium/large tasks.\n- `.shepherd/_design_feedback.md`: the human's iteration answers, verbatim\n  (orchestrator-written; triggers architect/criteria revision passes).\n- `.shepherd/_panel.json`: approved reviewer panel, resolved per-stage models, and\n  iteration limits.\n- `.shepherd/_state.json`: resumable phase and iteration state.\n- `.shepherd/_progress.md`: run log and resolved configuration notes.\n- `.shepherd/_design.approved`, `.shepherd/_create_pr.approved`: human approval markers.\n- `.shepherd/iter-N/`: per-iteration `claim.md`, review files, `fulfillment.md`, diff,\n  and test output (plus `baseline.txt` in `iter-1/`, the pre-change oracle metrics).\n\n### Why one file per stage\n\nThe files are not bookkeeping; they are the context-routing mechanism. Each stage writes\none file, and each role reads only what it needs. Chat is ephemeral — your feedback goes\nverbatim into `_design_feedback.md`, and subagents fold it into their files, so a run can\nresume from disk at any point. The architect never reads the success criteria; the\ncriteria author never sees the solution; reviewers judge pasted judgment files (design,\ncriteria, diff, tests) while reading the repository itself for ground truth, and stay\nblind to `claim.md` and to each other. Fulfillment reads `claim.md` for the claimed test\ndeltas but never the reviews. Blindness applies to judgments, never to ground truth: only\n`.shepherd/` judgment files are gated — the repository stays readable to every role.\n\nThat split is what makes multiple judgments produce independent signal. Collapsing the\nrun into one shared context would either pollute each role or break that independence.\n\n## Configuration\n\nStages are configured in `.shepherd/config.json`; defaults ship beside the skill in\n`.claude/skills/shepherd/config.default.json`. The base registry maps each `use` name to\na vendored engine under `.claude/skills/_vendored/`.\n\nDefault config:\n\n```json\n{\n  \"stages\": {\n    \"reviewers\": [{ \"use\": \"staff-review\", \"model\": \"auto\" }],\n    \"final_reviewers\": [\n      { \"use\": \"thermonuclear\", \"model\": \"auto\" },\n      { \"use\": \"ponytail-review\", \"model\": \"auto\" }\n    ]\n  },\n  \"oracle\": { \"commands\": [] },\n  \"limits\": { \"inner_iterations\": 3, \"final_review_rounds\": 2 },\n  \"plan_mode_gate\": true\n}\n```\n\nSingle stages (`verify`, `architect`, `implementer`, `success_criteria`, `fulfillment`)\nare optional: when absent, the built-in role table in the skill drives the stage with no\nengine. Assign an engine (`writing-plans`, `feature-dev`, `brainstorming`, or a repo\n`use` such as `dig`) only when you want its specific methodology.\n\nEach stage entry takes a `model`. `auto` (the default) lets shepherd pick per role and\ntriage tier — `haiku`/`sonnet`/`opus`, scaling up for larger changes and down for smaller\nones; a concrete name pins the stage. All `auto` picks are resolved and shown at the\ndesign gate, where you can adjust any before approving. A local\n`.shepherd/config.local.json` shallow-overrides `config.json` for one environment.\n\nUse finite, non-mutating oracle commands such as type checks, lint checks, builds, unit\ntests, and targeted integration tests. Avoid dev servers, watchers, fixers, cleanup\ncommands, inspectors, and eval workflows.\n\nMore detail:\n\n- Config reference: [docs/shepherd-config.md](docs/shepherd-config.md)\n- Vendored engine provenance: [VENDORED.md](VENDORED.md)\n\n## Vendored engines\n\nshepherd vendors optional stage engines (`brainstorming`, `writing-plans`,\n`feature-dev`, `staff-review`, `thermonuclear`, `code-review`, and `ponytail-review`)\nunder `_vendored/` so a fresh clone or plugin install works without extra plugin\ndependencies. `code-review` ships in the registry but is off the default final-reviewer\nroster; assign it explicitly in config to opt in.\n\nVendored engines are named `ENGINE.md`, not `SKILL.md`, so Claude Code does not register\nthem as slash commands. The registry's `scope` field adapts each engine to shepherd's\nfile protocol, and every dispatched stage runs non-interactively: it records open\nquestions in its output file instead of asking the human. See [VENDORED.md](VENDORED.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapify%2Fshepherd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapify%2Fshepherd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapify%2Fshepherd/lists"}