@irythill/orq 0.0.0-stage → 0.1.0

package/skills/issue/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: issue
+description: Runs a Plane issue end to end by orchestrating coding agents in herdr or any terminal (herdr-agent / orq agent + orq wait) — implementer and cross-vendor reviewer picked by orq pick, tests by herdr-verify / orq verify, comment and status in Plane. Use when the user says "/issue <ID>", "take issue X", "run ABC-123", or asks to check/create issues in the conductor's ecosystem.
+---
+
+# /issue <ID> — conductor playbook (herdr or any terminal)
+
+You are the **orchestrator**: you plan, dispatch, follow up and report. **Do not implement anything yourself** (it
+burns the conductor's model). Talk to the user in the user's language.
+
+**Ecosystem configuration:** the **workspace** `CLAUDE.md` (the folder named in your conductor instructions) defines
+the repositories and their groups (= herdr workspace, `-g`), **each repo's base branch**, verification commands,
+Plane projects (identifier → project_id), default assignee, labels/modules and MCP limitations. Read it before you
+start. Below, `$WS` = workspace.
+**Inside herdr** (`HERDR_ENV=1`): children open in herdr tabs and their notices reach your pane — the flow below.
+**Outside herdr** (any terminal, tmux, any OS): the same flow with these swaps —
+- `herdr-agent ...` → `orq agent ...` (same flags; it is the same program). Children run in tmux windows inside tmux,
+  else in the background (their screen goes to a log; the answer is still `<prefix>.out.md`). No `-T`.
+- `herdr-claim` → `orq claim` (set `ORQ_CONDUCTOR_ID` to a fixed name per conductor), `herdr-deps` → `orq deps`.
+- **Completion signal:** no line arrives in your pane. After dispatching, run `orq wait <prefix>` **as a background
+  task** (Claude Code: Bash with `run_in_background`); its exit wakes you and its output is the line
+  `[ORQ AGENT DONE] <title> status=ok|fail ... answer: <file>` — treat it exactly like `[HERDR-AGENT DONE]`. Several
+  children in parallel: `orq wait --any <prefix1> <prefix2>` (one wake-up per finish; wait again for the rest).
+  No background tasks in your harness → run `orq wait` in the foreground; that is the one allowed blocking wait.
+- `herdr-verify` → `orq verify`, `herdr-baseline` → `orq baseline` (same flags). They run in a tmux window or in
+  the background like children, and you wait for them the same way: `orq wait $O/verify-<repo>`.
+- Peeking at a child: `<prefix>.log` (not `herdr pane read`).
+Issue artifacts (prompts, notes) live in `$WS/.orquestra/<ID>/`.
+
+## 1. Read the issue
+- **First, claim it:** `herdr-claim -w $WS <ID>`. Exit 1 = another conductor owns it: **stop** and tell the user
+  (don't read it, don't dispatch anything). Taking it over (e.g. switching accounts) only with the user's OK:
+  `herdr-claim -w $WS -f <ID>`. Several conductors may share a workspace; `herdr-claim -w $WS -l` lists who has what.
+- `mcp__plane__workitem` `retrieve_by_identifier` with `workitem_identifier: "<ID>"`; then `workitem_comment list`.
+- Extract: goal, **acceptance criteria**, affected repos, links. No acceptance criteria → write a short proposal and
+  **ask the user** before dispatching.
+- Issue missing assignee, priority, labels or module → **fill them in** following the workspace `CLAUDE.md` "Issue
+  standard". The same standard applies to any new issue you create.
+- Move it to **In Progress** (`workitem update` with the state_id from `state list`).
+
+## 2. Classify
+One task per repo. Level:
+- **simple** — CRUD, UI/text tweak, localized bug, 1–3 files.
+- **medium** — business rule, API↔front integration, several files.
+- **heavy** — architecture, data migration, hard/concurrency bug, security.
+
+## 3. Pick agent and model: always `orq pick`, never by hand
+`orq pick` decides agent, model, effort and account (user config + delivery and token history + current quota +
+rotation). **Do not choose by preference, by a rule you read elsewhere, or by what worked last time**: run it before
+EVERY dispatch (implementation, review, second opinion) and use its output verbatim.
+```bash
+orq pick impl --level simple|medium|heavy                          # → e.g. -a codex -m gpt-6-sol -e low
+orq pick review --level <level> --impl-agent <agent that implemented>   # → another vendor, e.g. -a opencode -m ...
+orq pick opinion                                                   # second opinion (e.g. Copilot), see step 5
+```
+The output goes straight into `herdr-agent` (`herdr-agent $(orq pick ...) -g ... -t ... -d ... -o ... -- prompt.md`).
+- Exit 3 = no candidate (quota exhausted, no agent with that role): **stop and ask the user**.
+- Implementer failed review twice (step 6) → pick again without it: `orq pick impl --level <level> --exclude-agent <agent>`.
+- `--exclude-agent` never "sticks": every `orq pick` call decides again, with only that dispatch's exclusions.
+- The conductor's own model (e.g. Opus) as implementer: only with the user's OK, never through `orq pick`.
+- Want to understand a choice? `orq pick ... --explain --no-record` (score of each candidate; not counted in rotation).
+
+**Every child runs through `herdr-agent`** (agent from `orq pick`): headless (`claude -p` / `codex exec` /
+`opencode run` / `agy -p` / `copilot -p`) in a herdr tab (workspace = group `-g`, tab = title) with live output.
+When it finishes it writes `<prefix>.done` and sends ONE line `[HERDR-AGENT DONE] <title> status=ok|fail ...` to your
+pane; no MCP, and a **4 GB memory cap per agent** (own cgroup: if it blows up, only it dies). NEVER `herdr agent start`
+for children (no memory cap, no answer file). **Screen mode (`-T`, or `HERDR_AGENT_TUI=1`):** the tab shows the
+agent's own TUI instead of the log; same cap, same files, same signal (end-of-turn hook). The screen stays open after
+the turn (it holds memory until the tab closes); `-R` with the tab open types the follow-up into it. Use it when the
+user wants to watch. The repo must already be trusted in Codex/Claude (otherwise the TUI stops at the "trust this
+folder?" dialog — tell the user, don't approve it for them).
+
+## 4. Dispatch the implementer
+Write the prompt to `$WS/.orquestra/<ID>/impl-<repo>.md` (short: goal, acceptance criteria, likely files, the repo's
+verification commands, "base: origin/<BASE>; don't rebase/merge other branches; local commits, no push; commit
+messages following <path of the repo's commit conventions, see step 7>").
+Always include:
+- **Repo checklist:** copy the repo's "Checklist" column from the workspace `CLAUDE.md`.
+- **No tests in the child** (memory rule): "don't run jest/vitest; I run the related tests afterwards".
+- **Fresh branch:** "before your final answer: `git fetch origin <BASE> && git rebase origin/<BASE>`; on conflict stop
+  and report; after the rebase repeat lint/tsc". Codex has no network: for it, you fetch and check in step 5.
+
+**Base = the repo's base branch from the workspace `CLAUDE.md`, always from the updated remote (`origin/<BASE>`).**
+Worktree with `git worktree add` (not `herdr worktree create`: that opens a separate herdr workspace per worktree, and
+children are grouped by the repo's `-g`).
+```bash
+R=$WS/<repo>; BASE=<repo base>; B=<prefix>plane-<lowercase-id>; WT=$WS/.worktrees/<repo>-plane-<lowercase-id>
+O=$WS/.orquestra/<ID>
+git -C $R fetch origin $BASE
+git -C $R worktree add -b $B $WT origin/$BASE         # already exists? reuse $WT, don't recreate it
+git -C $WT log -1 --format='%h %s'                    # check HEAD == origin/$BASE before launching
+```
+**Dependencies — NEVER install inside the worktree** (each `node_modules` is ~1 GB and tens of thousands of files;
+on a modest disk that saturates I/O and memory and freezes the machine). The worktree uses a **link** to the main
+repo's `node_modules`:
+```bash
+herdr-deps -r $R -b $BASE -w $WT     # link; stale deps → fast-forward + ONE install in $R (per-repo lock across conductors)
+```
+Exit 3 = stale deps and `$R` dirty or not on `$BASE` → **ask the user**. If another conductor is installing in the
+same repo, the command waits its turn (never install by hand).
+In the child's prompt: "node_modules is shared (link): don't run install/add; if you need a new dependency, stop and
+tell me".
+**Dispatch** (no MCP; memory cap; writes in automatic mode — that is why implementation only happens in a worktree):
+```bash
+herdr-agent $(orq pick impl --level <level>) -g <group> -t "<ID> impl <repo>" -d $WT -o $O/impl-<repo> -- $O/impl-<repo>.md
+```
+- The Claude account (`-c`) already comes from `orq pick` (the least used one under the limit).
+- Full final answer in `$O/impl-<repo>.out.md`; log in `.log`; the agent's session id in `.id`.
+- Codex's sandbox has no network: `git fetch` is yours, beforehand (above). Push/PR: yours (step 7).
+- `herdr-agent` returns immediately (no need to background it); the child's pane is in `<prefix>.pane`
+  (`herdr pane read $(cat <prefix>.pane) --source recent` to peek).
+- **No baseline in the issue flow:** don't run `herdr-baseline` before dispatching (the base moves with every merge and
+  the full suite blocks every conductor's test queue). `herdr-verify` checks the base on demand (step 4b).
+- **Children start WITHOUT MCP** (Plane is yours; each MCP costs ~150–200 MB per session and `systemd-oomd` kills the
+  whole herdr server when memory runs out) — `herdr-agent` takes care of it.
+- Every child prompt ends with: "Don't try to talk to the conductor or use herdr; finish with your complete final
+  answer (that is what I read)."
+- **Verification in the child: lint and tsc only, one command at a time** (the cap is 4 GB per agent and jest/vitest
+  blow it; tests are yours, step 4b): use the Verification column of the workspace `CLAUDE.md` and put in the prompt
+  "verify sequentially, never in parallel or watch mode: (1) lint only the changed files (`git diff --name-only
+  origin/<BASE>...HEAD`); (2) `NODE_OPTIONS=--max-old-space-size=2048 tsc --noEmit` for the project. Don't run tests".
+  Full suite only in CI (or a manual `herdr-baseline` if the user asks).
+- An issue that changes an API contract: **API first**; consumers afterwards, with the new contract in the prompt.
+- **Never block waiting** (`herdr agent wait`, `pane wait-output`, `sleep`, `timeout`): completion arrives as a
+  `[HERDR-AGENT DONE]` line in your pane. Dispatch, report in one line and end your turn. "Done yet?" = `<prefix>.done`
+  exists (never `pgrep`).
+- Investigation only (no code): "READ ONLY" prompt, in the repo itself, no worktree. `herdr-agent -r` (Claude:
+  `--permission-mode plan`; the others: throwaway worktree, no editing).
+
+## 4b. Tests (yours, not the child's)
+Child with `status=ok` → run the tests related to the diff, in their own tab, one at a time on the machine (queue):
+`herdr-verify -w $WS -r <repo> -d $WT -b <BASE> -o $O/verify-<repo> -g <group>` → `$O/verify-<repo>.txt` with
+**new failures** and pre-existing ones: if any test fails, it runs the same test files on an updated
+`origin/<BASE>` (whatever fails there is pre-existing). You get `[HERDR-AGENT DONE] verify ... new=N`.
+`new>0` → fix round with the list (step 6), no review. `new=0` → review.
+**Mandatory order every round (impl and each fix): child `ok` → verify → review.** Never dispatch the review (or an
+"early" fix) while this round's verify is pending, even if it is queued behind another verify: wait for
+`[HERDR-AGENT DONE] ... verify ...` and end your turn until then.
+
+## 5. Cross review (always another vendor)
+```bash
+herdr-agent $(orq pick review --level <level> --impl-agent <who implemented>) -b $BASE \
+  -g <group> -t "<ID> review <repo>" -d $WT -o $O/review-<repo> -r -i $O/impl-<repo>.md -i $O/verify-<repo>.txt \
+  -- $O/review-<repo>.md
+```
+`-b $BASE` attaches the diff (`origin/$BASE...HEAD`): always use it. The review prompt works for any reviewer and says
+"the diff is attached; for context, open files with your file-reading tool; don't run lint, tsc or tests (the results
+are in the attached verify)". If the reviewer ends with `status=fail` and no verdict (empty answer, or a
+`jetski: ... permission` line), that is not a rejection: run `orq pick review ... --exclude-agent <it>` and redo it.
+`--exclude-agent` applies **only to redoing that review**: for the next round's review, run `orq pick review` without
+exclusions (the failure may have been a one-off). An agent that failed twice in a row with no verdict →
+`orq block <agent> --days 1` and tell the user.
+**Second opinion** (`orq pick opinion`, read only, same attachments): only on **heavy** issues or when reviewer and
+implementer disagree about a blocker. It never becomes a round by itself: you weigh both answers and decide.
+**Before dispatching:** `git -C $R fetch origin $BASE; git -C $WT merge-base --is-ancestor origin/$BASE HEAD` — if it
+fails, don't review yet: send a fix "rebase on origin/<BASE> and repeat the checks".
+Always **in the same worktree `$WT`**, with the prompt in `$WS/.orquestra/<ID>/review-<repo>.md` = acceptance
+criteria + "review only the attached diff; answer APPROVED or a numbered list of problems (blocker/suggestion)".
+Fixed review checklist, besides the criteria: (a) identifiers/keys consistent across the touched modules (same concept
+= same field); (b) dependency downgrade, override or pin → check the CVE/advisory behind the current version; (c) the
+repo checklist.
+
+## 6. Loop
+Blocking problems → write the list to `$O/fix-<n>.md` and continue the implementer's session (any agent):
+`herdr-agent -a <same> [-c <same account>] -g <group> -t "<ID> fix<n> <repo>" -d $WT -o $O/impl-<repo> -R $(cat $O/impl-<repo>.id) -- $O/fix-<n>.md`.
+A fix is a continuation: same agent and session, no `orq pick`. Then a new `herdr-verify` (4b) and a new review
+(`orq pick review` again). **Maximum: `orq config get policy.max_rounds` rounds**; over it → `orq pick impl
+--exclude-agent <it>` only with the user's OK, or stop and report. Non-blocking suggestions go into the comment; they
+don't become a round.
+
+## 7. Close
+**Commit/PR conventions belong to the repo, not to you.** The **implementer, in the worktree** (where the repo's
+rules live) commits and writes the PR. Find and cite in the prompt, by path, whatever the repo has:
+`.claude/skills/commit-conventions/SKILL.md` or `.agents/skills/commit-conventions/SKILL.md`,
+`.github/pull_request_template.md`, `commitlint.config.*`. None of those → plain Conventional Commits.
+- Commits: from step 4 on, the prompt says "follow <commit conventions path>". If the review flags a deviation, ask the
+  implementer for `git commit --amend`/`rebase -i` before the PR.
+- PR (**only when the user asks**): you, in `$WT`: `git -C $WT push -u origin <branch>` and `gh pr create` with a body
+  built **from the repo's `.github/pull_request_template.md`** (every section; `<ID>` where the template asks for the
+  issue) and the answer in `$O/impl-<repo>.out.md`. Check the opened PR against the template.
+- Plane comment (`workitem_comment create`): summary, repo(s), branch, agents and models used (`orq pick` output),
+  review result, checks that ran.
+- **CI after every push:** `gh pr checks <n>` (no `--watch`; if pending, end your turn and check on the next notice).
+  Red → `gh run view <id> --log-failed | tail -40`: error from the diff → fix round; error already on the base → create
+  a Plane issue (workspace standard) and tell the user. "Ready to merge" only with green checks or an explained failure
+  + issue.
+- Move it to **In Review** (finished child tabs close by themselves; close any leftover with
+  `herdr tab list | jq -r '.result.tabs[]|select(.label|startswith("<ID> "))|.tab_id' | xargs -rn1 herdr tab close`)
+  and **release the issue**: `herdr-claim -w $WS -r <ID>`. The worktree stays until the merge.
+- **After the merge** (when the user confirms): `git -C $R fetch origin $BASE; git -C $R cherry origin/$BASE <branch>`
+  with no `+` lines → `git -C $R worktree remove $WT` and `git -C $R branch -D <branch>`; with `+` lines → ask.
+- **Never** push, PR, merge or deploy unless the user asks. Report to the user in 3–5 lines.
+
+## Saving tokens
+Short prompts (never paste the whole `CLAUDE.md` — the agent reads the repo's own). Reviews judge only the diff, but the prompt must say the reviewer **may open files for context** (cat, rg, git
+show — read only): Codex read "review only the diff" as "use only the attached diff" and returned an empty review. Don't re-read
+the whole issue at every step. Respect the MCP limitations listed in the workspace `CLAUDE.md`.

package/skills/orq-setup/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: orq-setup
+description: Guided first-time setup of orq for a new developer — detects and smoke-tests the installed agent CLIs, asks which agents take which roles, models, Claude accounts and pick weights, writes ~/.config/orq/config.toml, then prepares a conductor workspace (orq setup --workspace + workspace CLAUDE.md) and checks Plane. Use when the user says "/orq-setup", "set up orq", "configure orq" or just installed orq (npm i -g @irythill/orq, or install.sh).
+---
+
+# /orq-setup — configure orq for this developer
+
+You are setting up orq for someone who just installed it (`npm i -g @irythill/orq`, or `install.sh` from a clone).
+Be brief, one step at a time. Talk to the user in the user's language. **Ask before writing or running anything that
+costs tokens or changes files**; show what you will write first. Never handle API keys or tokens yourself: tell the
+user where to put them.
+`$ORQ` = docs and examples: a clone of the repo if there is one, else https://github.com/irythill/orq (`docs/`,
+`examples/`; the npm package ships only the CLI, the skills and the workspace template).
+
+## 0. Preflight
+- `command -v orq` missing → tell the user to run `npm i -g @irythill/orq` and stop.
+- `orq setup --install`: shows what orq found (git, terminal host, memory cap, keyring, shell completion) and links
+  the skills for Claude Code. `git` missing → stop: it is required. herdr is optional (tabs per child; on Linux,
+  `$ORQ/install.sh` adds it as a service): without it children run in tmux windows or in the background.
+- Existing `~/.config/orq/config.toml` (or `config.json`)? Show it in short and ask: start over, or adjust it.
+
+## 1. Detect and smoke-test the agents
+- `command -v claude codex opencode agy copilot` → list what's installed (`agy` = Antigravity).
+- Offer one headless smoke test per agent found. Say that **each costs a few tokens** and needs the CLI logged in; run
+  only the ones the user approves (AskUserQuestion, multiSelect), one at a time, with a timeout:
+  ```bash
+  timeout 120 claude -p "reply ok"
+  timeout 120 codex exec --skip-git-repo-check "reply ok"
+  timeout 120 opencode run "reply ok"
+  timeout 120 agy -p "reply ok"
+  timeout 120 copilot -p "reply ok" -s
+  ```
+- Report a table: agent · installed · test ok/failed/skipped. Failed → likely not logged in: tell the user the login
+  command (`claude`, `codex login`, `opencode auth login`, `agy`, `copilot` then `/login`) and offer to retest. Only
+  agents that passed (or that the user insists on) go into the config.
+
+## 2. Agents and roles — `orq setup` suggests, the user decides
+Don't ask "which roles should this agent take?": newcomers can't answer that. Ask what they know (AskUserQuestion)
+and let `orq setup` apply the rules (src/suggest.ts):
+- per working agent: **plan** — `free` · `small` (Pro, Copilot Pro, monthly allowance) · `large` (Max, high tiers) ·
+  `payg` (API, MiniMax); its **vendor** only for agents orq doesn't know (opencode: the provider, e.g. `minimax`);
+- which one they **trust most** to write code (optional);
+- where they will **talk to orq** (the conductor): an agent name, or `other`;
+- how many tasks they usually run **in parallel**; how much **RAM** agents may use (suggest total RAM).
+Then write the answers to a temp file and show the proposal:
+```bash
+orq setup --answers /tmp/orq-answers.json      # {"agents":{"codex":{"plan":"large","trust":true},...},"conductor":"claude","parallel":3,"ramGB":16}
+```
+Explain each `# Why:` line in plain words and ask what to change. Whatever they fix becomes `[roles.<role>] agent = ...`;
+the rest stays `auto`. Presets for those who want no questions: `--preset economy | quality | single-agent`.
+**Models** (`models.<role>.<level> = "model[@effort]"`): optional — without them each CLI uses its default model.
+Offer `$ORQ/examples/irythill/config.toml` as an example, saying clearly **it is one person's choices**.
+**quota names:** what `orq quota` prints for that agent.
+
+## 3. Claude accounts
+- `claude-accounts` lists them. None and the user has more than one account → offer to create
+  `~/.config/claude-accounts` (lines `<name> <CLAUDE_CONFIG_DIR>`, e.g. `work ~/.claude`, `personal ~/.claude-personal`)
+  and explain the alias + one-time login from `$ORQ/docs/claude-accounts.md`. One account → skip; `quota = ["<name>"]`
+  only if listed there.
+- Re-run `orq setup --install` afterwards so the skills are linked into each account's folder too.
+
+## 4. Policy
+Explain simply, then suggest the example's values and ask if they want to change any:
+- `quota_limit` (90): an agent at or above this % of its 5h/weekly quota is left out.
+- weights — already suggested by `orq setup` from the parallel tasks: `quality` (did it deliver?), `tokens` (spent
+  little?), `speed` (finished fast?), `rotation` (penalty for being picked recently, spreads the work).
+- `max_rounds` (2) review rounds before handing back; `machine.agent_mem_max` / `test_mem_max` come from `orq setup`
+  (RAM and parallel tasks) — the user may change them.
+- **Language** of orq's messages (board, notices, CLI): `[ui] lang = "auto" | "en" | "pt"` (auto = system locale).
+  Suggest the language the user is talking to you in. Mention they can switch any time with `orq lang toggle`, the
+  `l` key in `orq board`, or a herdr key bound to the `orq.lang-toggle` action (see the comments in
+  `herdr-plugin/herdr-plugin.toml`).
+- **Board theme**: `[ui] theme = "gunmetal"` (default, dark) | `"chrome"` (light) | `"lcd"` (green) | `"terminal"`.
+  Light terminal → suggest `chrome`; they can cycle with `t` inside `orq board`.
+
+## 5. Write and validate
+- Show the full TOML (the proposal plus the changes they asked for). After the OK: `orq setup --answers <file> --write`
+  (backs up an existing config as `config.toml.bak-<timestamp>`), then apply their edits with `orq set` or by editing
+  the file.
+- Validate: `orq config files` and `orq config` (exit 2 = error: fix and retry).
+- Show the picks: `orq pick impl --level medium --explain --no-record` and
+  `orq pick review --impl-agent <their main implementer> --explain --no-record`. Exit 3 = no candidate: explain why
+  (roles, vendor, quota) and adjust.
+
+## 6. Workspace
+- Ask for the folder that groups their repos (e.g. `~/Code/acme-platform`). After the OK:
+  `orq setup --workspace <folder> --conductor <the conductor agent>` — `.orquestra/`, `.worktrees/`, the map
+  `<folder>/CLAUDE.md` from the template (never overwrites one) and the `/issue` playbook in the conductor's format
+  (`.claude/skills/issue/SKILL.md` for Claude Code, `AGENTS.md` for the others). Conductor in herdr (clone only):
+  `$ORQ/setup/new-conductor.sh <name> <folder>` also writes its instructions and permissions.
+- Fill the repo table in `<folder>/CLAUDE.md` by inspecting each git repo inside it:
+  - base branch: `git -C <repo> symbolic-ref --short refs/remotes/origin/HEAD` (strip `origin/`); ask if the team
+    branches from another one (e.g. `dev`).
+  - group: the repo folder name in lower case (the herdr workspace or tmux group for its children).
+  - stack and verification: `package.json` scripts (lint, typecheck, test) with the package manager from the lockfile;
+    otherwise `Makefile`, `pyproject.toml`, `Cargo.toml`, `go.mod`… Leave `—` when nothing fits.
+  Show the filled table and write it only after the OK. Plane projects and the issue standard: ask, or leave the
+  placeholders and say so.
+
+## 7. Plane
+- Point to `$ORQ/docs/plane.md` (on GitHub without a clone). Check `claude mcp list` (and `CLAUDE_CONFIG_DIR=<dir> claude mcp list` for every
+  account that will run a conductor) for a `plane` server.
+- Missing → tell the user to follow docs/plane.md; the API key goes in **their** MCP config, typed by them, never in
+  this chat or in a repo.
+
+## 8. Wrap up
+Short checklist: agents tested and enabled (roles), accounts, config path (+ backup), workspace and repos filled,
+Plane ok/pending, anything skipped. Then how to start:
+```bash
+cd <folder> && claude                     # any terminal (or codex, opencode… reading AGENTS.md)
+cd <folder> && herdr-conductor            # or inside a herdr pane (clone + install.sh)
+```
+and in the conductor: `/issue DEMO-123`. `orq board` in another tab shows everything; shell completion:
+`orq completion bash|zsh|fish|powershell` (the line to add is in `orq setup --install`).

package/skills/orq-status/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: orq-status
+description: Read-only summary of the orq orchestration in chat — test queue, running agents, conductors and their issues, quota per agent/account, active blocks and the recent scoreboard (orq stats). Use when the user says "/orq-status", "how's the queue", "what's running", "how much quota is left" or asks for an orq status report.
+---
+
+# /orq-status — orchestration status in chat
+
+**Read only.** Collect, summarize, stop. Do not dispatch, kill, unblock, or claim anything: if something looks
+wrong, point it out and suggest the command, but let the user decide. Talk to the user in the user's language.
+
+## 1. Collect (one Bash call, all in parallel is fine)
+```bash
+orq board --once 2>&1                                                            # queue, agents, conductors, quota
+orq block -l                                                                     # agents/accounts out of orq pick
+orq stats --days ${DAYS:-7}                                                      # scoreboard (default: last 7 days)
+```
+- `orq board --once` (plain text when piped; `--json` for exact fields) already gathers the test queue (TRANSPORT), running agents (TRACKS), conductors with their
+  claimed issues (MASTER) and quota (MIXER). Its quota comes from a cache refreshed in the background: if MIXER says
+  "collecting..." (or the cache is old and the user asked about quota), run `orq quota` directly instead.
+- The user passed a number (`/orq-status 30`)? Use it as `--days`. `-w <workspace>` → pass it to `orq stats -w` and
+  as `-w <workspace>` to the board.
+- A command missing or failing (e.g. herdr not running): say so in one line and summarize what the others returned.
+  `orq quota` exiting 1 is a known quirk (last agent not requested), not a failure — use its output.
+
+## 2. Summarize (short, scannable)
+Sections in this order; skip a section that is empty, saying so in one line ("queue empty", "no agents running"):
+1. **Test queue** — what is running (issue, repo, for how long) and how many are waiting.
+2. **Agents** — one line each: issue, label, agent·model, elapsed, memory. Flag ⚠ for >3 h running, memory near
+   the cap, or orphans (no `.run.sh`).
+3. **Conductors** — issue(s) and state; call out any **asking for approval** (the user must act there).
+4. **Quota** — per account/agent, the higher of 5h/week. Flag ≥70 % and ≥90 %; `?` = no data (log in again).
+   Add active blocks from `orq block -l` with their end date.
+5. **Scoreboard** — per agent: runs, first-pass approval, median duration, new tokens. Two or three lines, not the
+   whole table, unless the user asks.
+
+End with **at most two** suggested next actions, only when something needs attention (e.g. "Antigravity block
+ends 16/10: `orq block -r antigravity` when quota is back"; "conductor X is waiting for your approval").

package/templates/workspace.CLAUDE.md

@@ -0,0 +1,49 @@
+# CLAUDE.md — {{NAME}} ecosystem ({{WORKSPACE}})
+
+This folder groups the ecosystem's repositories. Each repo has its own `CLAUDE.md`/`AGENTS.md` with commands and
+rules — read the repo's own before touching it. This file only holds the map and the orchestration settings.
+
+## Orchestration (read by the `/issue` skill)
+- **Workspace:** `{{WORKSPACE}}`
+- **Conductor (herdr):** opened with `herdr-conductor [account] [model] [-r <session-id>]` in a herdr pane, in this folder
+  (instructions in `.orquestra-conductor.md`); the **Group** in the table below is the herdr workspace (`-g`).
+  Tests from the Verification column (jest/vitest) **don't run in the child**: the conductor runs `herdr-verify` (`orq verify`
+  outside herdr; one at a time on the machine); the child does lint + `tsc` (`NODE_OPTIONS=--max-old-space-size=2048`).
+- **Agents:** chosen by `orq-pick` from each developer's `~/.config/orq/config.toml` — nothing about models here.
+
+## Repositories
+
+| Folder | What it is | Stack / PM | Group | Base | Verification | Checklist |
+|---|---|---|---|---|---|---|
+| `{{repo}}` | {{description}} | {{stack}} | `{{group}}` | `dev` | `{{lint}}`, `{{typecheck}}`, `{{test}}` | {{what every implementer must remember in this repo, or —}} |
+
+## How they connect
+- {{who consumes whom; what changes first when a contract changes}}
+
+## Branches
+- Work starts from an **updated `origin/<Base>`** (Base column) and comes back through a PR to the same base.
+- **Branch prefix:** `{{prefix, e.g. your-user/ — or empty}}` → one branch per issue `<prefix>plane-<lowercase-id>`.
+  Worktrees in `{{WORKSPACE}}/.worktrees/<repo>-plane-<id>`.
+- Commit/PR conventions live **in each repo** (`.claude|.agents/skills/commit-conventions`,
+  `.github/pull_request_template.md`, `commitlint`) — don't copy them here; the `/issue` skill tells the implementer
+  to follow them.
+- **Never** merge, push to the base/`main` or deploy unless the user asks.
+
+## Plane ({{PLANE_URL}}, workspace `{{SLUG}}`)
+| Project | Identifier | project_id | Repos |
+|---|---|---|---|
+| {{name}} | `{{ID}}` | `{{uuid}}` | {{repos}} |
+
+States: Backlog → Todo → In Progress → **In Review** → Done.
+
+### Issue standard (when creating or triaging)
+- **State**: `Todo` if ready, `Backlog` if still an idea.
+- **Assignee**: `{{user}}` → `{{user_id}}`.
+- **Created by**: automatic (owner of the MCP token).
+- **Priority**: `urgent` / `high` / `medium` (default) / `low`.
+- **Labels**: {{convention — e.g. 1 type + at least 1 area}}.
+- **Module**: pick an existing, active one; none fits → propose one to the user before creating it.
+- **Parent/relation** to the originating issue, when there is one.
+
+### MCP limitations
+- {{e.g. don't use `pql`; `workitem count` returns 404}}