@irythill/orq 0.7.0 → 0.9.0

package/skills/issue/SKILL.md

@@ -8,7 +8,7 @@ description: Runs a Plane issue end to end by orchestrating coding agents in her
 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
+**Ecosystem configuration:** in the folder named in your conductor instructions, read `ORQ.md` (legacy: `CLAUDE.md`). It defines
 the repositories and their groups (= herdr workspace or just a label, `-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.
@@ -17,11 +17,17 @@ herdr (`HERDR_ENV=1`), in tmux windows inside tmux, else in the background (thei
 still `<prefix>.out.md`; `-T`, the agent's own screen, needs herdr or tmux). Set `ORQ_CONDUCTOR_ID` to a fixed name per
 conductor outside herdr.
 - **Completion signal:** in herdr, one line `[HERDR-AGENT DONE] <title> status=ok|fail ... answer: <file>` is typed into
-  your pane after each child. Anywhere else no line arrives: 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
+  your pane after each child. Anywhere else no line arrives: `orq wait <prefix>` prints
   `[ORQ AGENT DONE] <title> status=ok|fail ... answer: <file>`. Treat both lines the same. 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.
+  `orq wait --any <prefix1> <prefix2>` (one finish per call; wait again for the rest).
+- **Waiting strategy** (your conductor instructions name it; `orq instructions strategy` shows it). It depends on what
+  your harness can do, not on whether it can start a background process:
+  - *background task* — only when a finished background task starts a new turn by itself (Claude Code: Bash with
+    `run_in_background`): run `orq wait --any ...` that way and end your turn.
+  - *foreground loop* — every other harness (Codex, OpenCode, ...): stay active. Run
+    `orq wait --any --timeout <s> <pending prefixes>` in the foreground; exit 124 = nothing finished yet → one-line
+    status to the user and run it again (never re-dispatch on a timeout). Don't end your turn expecting a wake-up; if
+    you must, tell the user you won't continue until they message you.
 - `orq verify` and `orq baseline` run like children (herdr tab, tmux window or background) and you wait for them the same
   way, e.g. `orq wait $O/verify-<repo>`.
 - Peeking at a child: `<prefix>.log` (in herdr also `herdr pane read $(cat <prefix>.pane) --source recent`).
@@ -42,7 +48,7 @@ Issue artifacts (prompts, notes) live in `$WS/.orquestra/<ID>/`.
 - `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
+- Issue missing assignee, priority, labels or module → **fill them in** following the workspace `ORQ.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`).
 
@@ -93,7 +99,7 @@ Write the prompt to `$WS/.orquestra/<ID>/impl-<repo>.md` (short: goal, acceptanc
 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`.
+- **Repo checklist:** copy the repo's "Checklist" column from the workspace `ORQ.md`.
 - **Decisions:** "end your final answer with a `## Decisions` section, at most 10 lines: what you chose and what you
   ruled out, trade-offs, and what you left out on purpose and why". The reviewer reads it (step 5), so a deliberate
   choice doesn't come back as a blocker.
@@ -102,7 +108,7 @@ Always include:
   and report; after the rebase repeat lint/tsc". An agent without network (Codex) can't fetch: `orq agent` fetches before
   the run and adds a note to its prompt, so it only rebases locally.
 
-**Base = the repo's base branch from the workspace `CLAUDE.md`, always from the updated remote (`origin/<BASE>`).**
+**Base = the repo's base branch from the workspace `ORQ.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
@@ -139,7 +145,7 @@ orq agent $(cat $O/impl-<repo>.pick) -g <group> -t "<ID> impl <repo>" -d $WT -o
 - 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
+  blow it; tests are yours, step 4b): use the Verification column of the workspace `ORQ.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 `orq baseline` if the user asks).
@@ -148,7 +154,7 @@ orq agent $(cat $O/impl-<repo>.pick) -g <group> -t "<ID> impl <repo>" -d $WT -o
   arriving), run `orq notice` (delivery log) and `<prefix>.done` for that issue, then handle the failure; running
   `orq wait`, `orq verify` or `orq agent` for the issue acknowledges it.
 - **Never block waiting** (`herdr agent wait`, `pane wait-output`, `sleep`, `timeout`): completion arrives as a
-  `[HERDR-AGENT DONE]` line in your pane (herdr) or through the background `orq wait`. Dispatch, report in one line and end your turn. "Done yet?" = `<prefix>.done`
+  `[HERDR-AGENT DONE]` line in your pane (herdr) or through `orq wait` per your waiting strategy. Dispatch, report in one line, then end your turn (herdr / background task) or keep looping (foreground loop). "Done yet?" = `<prefix>.done`
   exists (never `pgrep`).
 - Investigation only (no code): "READ ONLY" prompt, in the repo itself, no worktree. `orq agent -r` (Claude:
   `--permission-mode plan`; the others: throwaway worktree, no editing).
@@ -169,7 +175,7 @@ something is red, new or old, and never widen a baseline or allowlist to silence
 outside the issue's domain: ask the user first (then it ships as its own PR, not as a note).
 **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
-the `... verify ...` done line and end your turn until then.
+the `... verify ...` done line (end your turn or keep looping, per your waiting strategy).
 
 ## 5. Cross review (always another vendor)
 ```bash
@@ -265,7 +271,7 @@ rules live) commits and writes the PR. Find and cite in the prompt, by path, wha
   high severity, `file:line` and a concrete failure, not already decided in the rounds, goes into a fix round (it
   counts towards `policy.max_rounds`); the rest goes into the Plane comment or a follow-up issue. Don't re-request the
   bot's review to "get it clean".
-- **CI after every push:** `gh pr checks <n>` (no `--watch`; if pending, end your turn and check on the next notice).
+- **CI after every push:** `gh pr checks <n>` (no `--watch`; if pending, check again on the next notice or loop iteration).
   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.
@@ -279,4 +285,4 @@ rules live) commits and writes the PR. Find and cite in the prompt, by path, wha
 ## 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`.
+the whole issue at every step. Respect the MCP limitations listed in the workspace `ORQ.md`.

package/skills/orq-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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).
+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 ORQ.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
@@ -85,10 +85,10 @@ Explain simply, then suggest the example's values and ask if they want to change
 ## 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
+  `<folder>/ORQ.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:
+- Fill the repo table in `<folder>/ORQ.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).

package/templates/conductor.instructions.md

@@ -2,23 +2,26 @@
 
 You orchestrate agents in the `{{WORKSPACE}}` ecosystem, in herdr (`HERDR_ENV=1`) or in any other terminal.
 Don't write code yourself. Opened by `orq conductor`. Talk to the user in the user's language.
-1. Read `{{WORKSPACE}}/CLAUDE.md` (repos, groups, base branch, Plane, issue standard, MCP limitations).
-2. For every Plane issue, follow the `/issue <ID>` skill.
+1. Read `{{WORKSPACE}}/ORQ.md` (repos, groups, base branch, Plane, issue standard, MCP limitations).
+   In an older workspace without `ORQ.md`, read `{{WORKSPACE}}/CLAUDE.md`.
+2. For every Plane issue, follow the `/issue <ID>` playbook (a skill or the generated block in `AGENTS.md`).
 3. Never push, open a PR, merge or deploy unless the user asks. When unsure about scope or cost, ask.
 4. **Children only through `orq agent`** (implementer, fix, review), with the agent chosen by `orq pick`; tests through
    `orq verify` (it checks the base by itself; no `orq baseline` in the flow), as the skill says. NEVER
    `herdr agent start` for children (no memory cap, no answer file); to watch the agent's own screen, `orq agent -T` (herdr or tmux).
 5. **Completion = one single signal:** in herdr, the line `[HERDR-AGENT DONE] <title> status=ok|fail ... answer: <file>`
-   arriving in your pane; elsewhere, `orq wait <prefix>` (as a background task) printing
-   `[ORQ AGENT DONE] <title> status=ok|fail ... answer: <file>` (plus the `<prefix>.done` file either way). When it
-   arrives: read the answer file and act. Nothing else means done.
+   arriving in your pane; elsewhere, `orq wait` printing `[ORQ AGENT DONE] <title> status=ok|fail ... answer: <file>`
+   (plus the `<prefix>.done` file either way), run as the **Waiting strategy** below says. When it arrives: read the
+   answer file and act. Nothing else means done.
 6. **"Is it still running?"** is answered by the file only: `<prefix>.done` exists → finished; it doesn't → running;
    check `<prefix>.log` (last write time) or, in herdr, peek at the pane: `herdr pane read $(cat <prefix>.pane) --source recent`.
    NEVER `pgrep`/`ps` (they match their own command line).
-7. **Never block waiting** (`herdr agent wait`, `pane wait-output`, `sleep`): dispatch, report in one line and end
-   your turn (outside herdr: `orq wait` in the background, never in the foreground unless your harness has no background tasks).
+7. **Never block waiting** (`herdr agent wait`, `pane wait-output`, `sleep`) except through `orq wait` as the Waiting
+   strategy below says. End your turn after dispatching only when that strategy gives you a wake-up.
 8. Worktrees always from `origin/<repo base>`, created with `git worktree add` (never `herdr worktree create`).
-9. Between batches of unrelated issues, suggest `/clear` to the user: state lives in Plane and in `.orquestra/`.
+9. Between batches of unrelated issues, suggest a fresh conversation: state lives in Plane and in `.orquestra/`.
+
+{{WAIT_STRATEGY}}
 
 ## How you are used
 - **Dispatcher, not consultant.** Your job: issue → dispatch → report → PR/cleanup. Long questions about architecture,
@@ -26,6 +29,6 @@ Don't write code yourself. Opened by `orq conductor`. Talk to the user in the us
   to a design session; come back with the decision recorded in the issue".
 - **The issue is the source.** A decision made in chat → record it in Plane (description or comment) before
   dispatching; the child's prompt comes from the issue, not from the conversation.
-- **Context:** past ~150k tokens or after closing a batch of related issues → suggest `/clear` (state in Plane and in
+- **Context:** past ~150k tokens or after closing a batch of related issues → suggest a fresh conversation (state in Plane and in
   `.orquestra/`).
 - 1–3 line answers. Final issue report: 3–5 lines + the PR link.

package/templates/workspace.CLAUDE.md

@@ -1,11 +1,11 @@
-# CLAUDE.md — {{NAME}} ecosystem ({{WORKSPACE}})
+# ORQ.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:** opened with `orq conductor [account] [model] [-r <session-id>]` in this folder, in any terminal (inside a
+- **Conductor:** opened with `orq conductor [agent] [account|-] [model] [-r <session-id>]` in this folder, in any terminal (inside a
   herdr pane too; `herdr-conductor` still works there). Instructions in `.orquestra-conductor.md`; the **Group** in the
   table below is the herdr workspace (`-g`) or just a label outside herdr.
   Tests from the Verification column (jest/vitest) **don't run in the child**: the conductor runs `orq verify`