You work on a repo that uses project-dev-orchestration, with your own agent (Claude Code, Codex or Grok Build) on your own machine. You don’t need the orchestrator, herdr, or any of the engine’s scripts; those are for whoever runs the team.
Read the repo’s own human guide as well: docs/agent-workflow.md in that repo (generated by /project-setup).
It has that repo’s labels, QC setup and any project-specific QC commands, changelog rule, and who to ask. Where it and this page
disagree, the repo’s guide wins.
| Tool | Install |
|---|---|
| Claude Code | /plugin marketplace add binerbuddy/project-dev-orchestration, then /plugin install project-dev-orchestration@project-dev-orchestration |
| Codex | codex plugin marketplace add binerbuddy/project-dev-orchestration, then codex plugin add project-dev-orchestration@project-dev-orchestration |
| Grok Build | grok plugin install binerbuddy/project-dev-orchestration |
Updating. Agents load the plugin when a session starts, so start a new session after updating.
| Tool | Update |
|---|---|
| Claude Code | claude plugin marketplace update project-dev-orchestration, then claude plugin update project-dev-orchestration@project-dev-orchestration |
| Codex | codex plugin marketplace upgrade project-dev-orchestration, then codex plugin add project-dev-orchestration@project-dev-orchestration |
| Grok Build | grok plugin update |
Install the whole plugin, not single skills: they share reference files. In Claude Code a skill may show up
namespaced, as /project-dev-orchestration:project-<name>; it’s the same skill as /project-<name>.
AGENTS.md (“How work flows here”) and .agents/project-profile.md (build commands, dev
servers, QC data). You don’t need to read them..agents/local/guide-ack (per clone, gitignored) and won’t ask again, unless the guide
changes..agents/project-profile.md, no “How work flows here” in AGENTS.md): run
/project-setup repo-only. It detects the build commands, drafts the profile, the AGENTS.md section and the
human guide, creates the missing labels, asks only what it can’t detect, and opens a PR on
chore/agent-workflow-setup for a maintainer to merge.| When | Run |
|---|---|
| You want the rules explained, or aren’t sure what applies | /project-how-it-works |
A route:small issue: a bug fix or small feature |
/project-small-feature-or-bug-fix <issue, e.g. #123, or a description> |
A route:design issue: a big or cross-cutting feature |
/project-feature-design <the feature, or its issue> |
A route:build issue: the design doc is ready |
/project-feature-build <path to the design doc> |
| You’re asked to review a PR | /project-pr-review <PR#> |
| Review comments on your PR need answering | /project-pr-triage <PR#> |
| You found a bug or have an idea | /project-intake <what you saw or want> |
| “Where are things?” | /project-status (read-only) |
| Your merged branches and worktrees pile up | /project-cleanup-worktrees |
| The repo isn’t set up, or its setup has drifted | /project-setup repo-only |
Only take issues a maintainer gave you, or ask first. An issue assigned to someone is theirs, and the orchestrator
skips it too. An issue labelled managed-by:<manager> is being worked by that manager’s agents (its claim comment
names them): don’t start it; ask that manager. An issue GitHub shows as “blocked by” an open issue waits for it.
| Label | Meaning |
|---|---|
route:small / route:design / route:build |
Which lifecycle the work follows (the table above). |
P1-urgent … P4-low |
Priority. Maintainers set it. A PR takes the highest P-label of the issues it closes, automatically. |
needs-triage |
Filed but not yet prioritised. Put it on anything you file. |
ready for QC |
The agent is done; the PR’s QC checklist is a human’s to work. |
QC complete - ready to review |
A human passed QC. Only a human applies it. |
awaiting-ux-gate |
An agent waits for a human to sign off a prototype. |
likely-fixed |
An agent thinks the issue is already done; a maintainer confirms and closes. |
epic-phase |
One phase of an epic; worked only as part of the epic’s build. |
on-hold, blocked-by-pr, Security |
Parked; can’t merge before another PR; ranks first in its priority. |
managed-by:<manager> |
Claimed by that manager’s agents. Ask that manager before touching it. |
A repo may rename the priority and QC labels; its human guide lists the names it uses.
Every PR that changes what users see carries one comment headed QC Checklist: steps to try in the running app,
naming data the way the app does (never a localhost link or an id). The first item links test data when the seed
data doesn’t cover a case; it lives on the never-merged qc-fixtures branch. In a repo with no UI (an engine or a
library), the checklist’s items are inputs (fixture files, requests to replay) with the expected output for each,
and the command that checks them.
| You want to | Do this |
|---|---|
| Give feedback or answer the agent’s questions | Submit a PR review with Request changes. Where the team runs the orchestrator, the PR’s agent gets it, fixes, pushes, replies on the PR, and re-labels ready for QC. |
| Pass QC | Add the QC complete - ready to review label (and remove ready for QC). Only a human does. |
Only reviews from the repo’s owners, members and collaborators count. GitHub won’t let you request changes on a PR you opened yourself; tell the agent in its session instead. Where no orchestrator runs, point the agent that built the PR at your review. Some repos add their own commands (a hosted preview, comment triggers): the repo’s human guide lists them.
Closes #<n>, and stops at ready for QC. It never merges.gh auth switch (the account is machine-wide); it pins one per command:
GH_TOKEN=$(gh auth token -u <you>) gh …. git push needs the token too:
pdo with-gh-user --user <you> git push … with the engine, else
GH_TOKEN=$(gh auth token -u <you>) git -c credential.https://github.com.helper= -c 'credential.https://github.com.helper=!gh auth git-credential' push ….Other repos. Your agent asks you before touching any repo other than the one it’s working in. Reading another
repo for context is fine. Editing its files, branches, pushes, PRs, issues, comments, labels or closes there wait for
your yes, and so does a Closes <org>/<other-repo>#<n> line, since merging closes that issue.
Open an issue in the right repo with the needs-triage label and no priority, and say who reported it.
/project-intake <what you saw> writes it for you: it checks for duplicates, drafts a Summary / Details / Starting
points issue, and files after your OK. Don’t fix out-of-scope things in passing. (Where the team runs the engine,
agents queue reports for an intake agent instead; a maintainer triages that queue.)
QC complete - ready to review without doing the QC.on-hold, needs-triage or epic-phase issues, on someone else’s assigned issue, or on an
issue another manager holds (managed-by:) or that is “blocked by” an open issue..agents/local/, fixtures, or anything the profile’s “Do not” lists.If this repo belongs to a work org and you also work your own repos on the same machine (with agents in
both), never run gh auth switch: gh has one active account per machine, and a switch breaks the other
sessions. The engine ships a gh shim that picks the login per repo owner instead. You need a checkout of
this repo for it (not the orchestrator):
git clone https://github.com/binerbuddy/project-dev-orchestration ~/src/project-dev-orchestration
$EDITOR ~/.config/project-dev-orchestration/gh-identities
# acme-corp alice-work alice@acme-corp.example Alice Example
# alice alice alice@example.com
# default alice
~/src/project-dev-orchestration/bin/install --gh-identities
# add the printed `export PATH=...shims:$PATH` line to your shell profile, open a new shell
~/src/project-dev-orchestration/bin/install --gh-identities --check
Every gh call then runs as the owner’s login, and git uses that login’s token and the map’s commit email
in that owner’s repos. Each login must be in gh once (PDO_GH_ALLOW_SWITCH=1 gh auth login). Undo with
bin/install --gh-identities --uninstall; it removes the one include line it added to your gitconfig and
keeps the map.
See also the FAQ, and the maintainers’ page if you run the team.