@irythill/orq 0.1.0 → 0.3.0

package/skills/orq-setup/SKILL.md

@@ -1,114 +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`).
+---
+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

@@ -1,37 +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").
+---
+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

@@ -1,49 +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}}
+# 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}}