@irythill/orq 0.3.0 → 0.4.0

package/skills/issue/SKILL.md

@@ -30,7 +30,15 @@ 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.
+  `herdr-claim -w $WS -f <ID>`. Several conductors may share a workspace; `herdr-claim -w $WS -l` lists who has what,
+  with each conductor's name (its herdr workspace label, e.g. "emp: orq-cms-dsgn"; outside herdr, `ORQ_CONDUCTOR_ID`).
+- **The user names another conductor** ("take over orq-cms-dsgn's work"): never guess a pane id. Run
+  `orq claim -w $WS --from "<what they said>"` (any part of the name works). It lists that conductor's issues; exit 3 =
+  the name matches more than one conductor (show the list, ask which); exit 1 = none. With the user's OK,
+  `orq claim -w $WS --from "<name>" -f` takes them all. **Resuming** an issue someone else started: don't start over.
+  Read `$O/` first — `impl-<repo>.md`/`.out.md` (prompt, answer, `## Decisions`), `.pick` files, the last
+  `fix-<n>.md` and `review-<repo>.out.md`, `verify-<repo>.txt` — and the Plane comments, then go on from the step the
+  files show (a `.pane`/`.id` without `.done` = a child still running: `orq wait` for it instead of dispatching again).
 - `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.
@@ -44,6 +52,14 @@ One task per repo. Level:
 - **medium** — business rule, API↔front integration, several files.
 - **heavy** — architecture, data migration, hard/concurrency bug, security.
 
+**Scope check, before dispatching.** Estimate the size. Split into sub-issues or sequential batches (each its own PR)
+when it touches several unrelated areas, changes roughly >400 lines, mixes refactor with behavior change, or has
+independent acceptance criteria.
+- Each batch is independently testable and reviewable; dispatch in order, one implementer per batch. Record the split in
+  Plane (sub-issues or a checklist comment) before starting.
+- Scope too big mid-run (reviews hitting `policy.max_rounds`, repeated findings, the implementer asking to change
+  scope): stop, split the remainder, don't force more rounds.
+
 ## 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
@@ -51,8 +67,10 @@ EVERY dispatch (implementation, review, second opinion) and use its output verba
 ```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
+orq pick opinion --impl-agent <agent that implemented>             # second opinion (e.g. Copilot), see step 5
 ```
+More than one agent eligible for `review`/`opinion` (declared, not excluded or blocked, with a model for the role; quota is not considered) and neither `--impl-agent` nor `--impl-vendor` given → exit 2:
+always pass one of them (`--no-record`/`--explain` do not change this).
 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>`.
@@ -108,7 +126,7 @@ tell me".
 orq pick impl --level <level> > $O/impl-<repo>.pick    # the fix rounds reuse it (step 6)
 herdr-agent $(cat $O/impl-<repo>.pick) -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).
+- The Claude account (`-c`) already comes from `orq pick` (one under the limit whose pace stays within it, then the least used).
 - 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`
@@ -161,6 +179,13 @@ are in the attached verify)". If the reviewer ends with `status=fail` and no ver
 `--exclude-agent` applies **only to redoing that review** (save the new pick to `review-<repo>.pick`); the next
 round reuses whoever gave the verdict. An agent that failed twice in a row with no verdict →
 `orq block <agent> --days 1` and tell the user.
+**Review tools** (an agent whose `run` has no `{prompt}`/`{prompt_text}`/stdin, e.g. a CodeRabbit-like CLI with
+`ok_exit`/`filter` in the config): same command; it ignores the prompt and the attachments and reviews the branch
+against `{base}` itself. Read its answer like any other: `status=ok` with `rc≠0` is a verdict with findings, not a
+failure. Its high-severity items are the blockers, still under the step 6 rule (`file:line` + concrete failure).
+If the tool's answer opens with (or, when short, consists of) a statement that nothing was reviewed (e.g. Corvus's "Nada para revisar"), `agents.<name>.no_review` (a
+regex) makes `orq agent` end that run `status=fail`: `orq pick`'s fallback and the conductor treat it as not run,
+same as an empty answer.
 **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
@@ -180,7 +205,7 @@ repo checklist.
 **Only `[blocker]` items open a round.** An item tagged blocker without `file:line` and a concrete failure, or that
 only restates a `## Decisions` choice, counts as a suggestion; when you downgrade one, say why in the Plane comment.
 No blockers left → APPROVED, even with suggestions.
-Blocking problems → write the list (blockers only) to `$O/fix-<n>.md` and continue the implementer's session (any agent):
+Blocking problems → write the list (blockers only) to `$O/fix-<n>.md` (always this name; reviews `$O/review-<repo>-<n>`, never `fix<n>-<repo>` or other variants — a later conductor counts rounds by these files) and continue the implementer's session (any agent):
 `herdr-agent $(orq pick fix --same $O/impl-<repo>.pick) -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, model, account and session, effort one level up (`--same` reads the implementer's
 pick; never a new `orq pick`, never `-a` alone — without `-m` the session resumes on the CLI's default model, which
@@ -196,10 +221,18 @@ Then a new `herdr-verify` (4b) and the **round review** (step 5 with these chang
   (the full `-b $BASE` diff stays, as context).
 - The prompt asks a closed question: "for each item in fix-<n>.md: RESOLVED or NOT RESOLVED (why); then the fix diff:
   any regression it introduced, as `[blocker]`/`[suggestion]`. Outside the fix diff, report only a blocker you missed
-  before that would break production, and say why it wasn't in the first review". Anything else is a suggestion. **Maximum: `orq config get policy.max_rounds` rounds**; over it → `orq pick impl
+  before that would break production, and say why it wasn't in the first review". Anything else is a suggestion. A review tool can't answer that: it reviews the whole
+branch again, so you do the matching — a finding is a blocker this round only if it is inside `fix-<n>.diff` or is a
+NOT RESOLVED item of `fix-<n>.md`; one you already decided on (fixed, rejected or downgraded) stays decided. **Maximum: `orq config get policy.max_rounds` rounds** — `orq agent -R` refuses the next one (exit 4) and counts per session, so a renamed prefix doesn't reset it; on exit 4 stop and tell the user, `-F` only with their OK; over it → `orq pick impl
 --exclude-agent <it> > $O/impl-<repo>.pick` only with the user's OK, or stop and report. Non-blocking suggestions go into the comment; they
 don't become a round.
 
+## Screenshots / visual validation
+Only when the issue asks for it. **One** attempt (a job with `--effort low`, a short prompt that says which screens and
+where to save the images), at most ~6 images, and read them only as files you need to judge — never re-read the same
+image. If it fails, tell the user instead of dispatching a second `shots` job. Playwright runs inside that child's
+worktree, never as an MCP in the conductor (images in the conductor's context are re-billed every turn).
+
 ## 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:
@@ -212,6 +245,10 @@ rules live) commits and writes the PR. Find and cite in the prompt, by path, wha
   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.
+- **Review bots on the PR** (a GitHub App reviewer): one more input, not a new review cycle. Only a finding with
+  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).
   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

package/skills/orq-setup/SKILL.md

@@ -61,7 +61,7 @@ Offer `$ORQ/examples/irythill/config.toml` as an example, saying clearly **it is
 
 ## 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.
+- `quota_week` (95) and `quota_5h` (simple 90, medium 85, heavy 80): an agent at or above these % 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`

package/templates/workspace.CLAUDE.md

@@ -11,6 +11,13 @@ rules — read the repo's own before touching it. This file only holds the map a
   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.
 
+## Scope
+- Before dispatching, split big issues into sub-issues or sequential batches (one PR, one implementer each) when they touch
+  several unrelated areas, change roughly >400 lines, mix refactor with behavior change, or have independent acceptance
+  criteria. Each batch must be testable and reviewable on its own; record the split in Plane before starting.
+- Reviews hitting `policy.max_rounds`, repeated findings or the implementer asking to change scope mean it was too big:
+  stop and split the remainder instead of forcing more rounds.
+
 ## Repositories
 
 | Folder | What it is | Stack / PM | Group | Base | Verification | Checklist |