llm-orchestrator 1.3.1 → 1.5.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "llm-orchestrator",
   "description": "Write /task once — it plans the work, shards it across parallel subagents, gates every phase and verifies before claiming done. Claude Code, Codex, OpenCode, Kilo.",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "author": {
     "name": "Bogdan-Gabriel Torcescu",
     "url": "https://www.linkedin.com/in/bogdantorcescu/"

package/README.md

@@ -86,9 +86,16 @@ No clone, no Node invocation. Type these two in any Claude Code session:
 ```
 
 That registers the `orchestrate-core` skill straight from this repository, and `/plugin update
-llm-orchestrator@tbogdan` keeps it current. The plugin ships the skill and its resources only — it
-does not write project files. If you also want `.claude/commands/*.md`, the `.claude/agents/orchestrator.md`
-agent and the `@AGENTS.md` line in `CLAUDE.md`, run the CLI install below with `--harness claude`.
+llm-orchestrator@tbogdan` keeps it current. The plugin also ships the native commands (`/task`,
+`/task-plan`, `/task-status`, `/task-cancel`, `/task-verify`, `/incident-*`, `/orchestrate`),
+namespaced by the plugin as `/llm-orchestrator:task` and so on; the bare `/task` works too while no
+other command claims the name — but a CLI install (below) also writes a project
+`.claude/commands/task.md`, and once both are present the bare `/task` resolves ambiguously between
+them, so pick one install path, or always use the namespaced `/llm-orchestrator:task`. It does not
+write project files. If you also want `.claude/commands/*.md`, the per-role agent files under
+`.claude/agents/` (one per role in `registries/agent-roles.json`, written only with
+`--with-agents`) and the `@AGENTS.md` line in `CLAUDE.md`, run the CLI install below with
+`--harness claude`.
 
 ### Codex, OpenCode, Kilo — install from npm
 
@@ -119,8 +126,8 @@ node bin/llm-orchestrator.mjs install --project /path/to/app --harness <harness>
 
 | Harness | Fastest install | What it gives you | Reload |
 | --- | --- | --- | --- |
-| Claude Code | `/plugin install llm-orchestrator@tbogdan` | the `orchestrate-core` skill | new session |
-| Claude Code (full) | `npx llm-orchestrator install --harness claude --apply` | skill + commands + agent + `CLAUDE.md` binding | `/reload` or new session |
+| Claude Code | `/plugin install llm-orchestrator@tbogdan` | the `orchestrate-core` skill, `/llm-orchestrator:task` and the other commands, the role agents | new session |
+| Claude Code (full) | `npx llm-orchestrator install --harness claude --apply` | skill + commands (+ role agents with `--with-agents`) + `CLAUDE.md` binding | `/reload` or new session |
 | Codex | `npx llm-orchestrator install --harness codex --apply` | `AGENTS.md` span, skill, `~/.codex/prompts/*.md` | new Codex session |
 | OpenCode | `npx llm-orchestrator install --harness opencode --apply` | `.opencode/command(s)/*.md`, skill | restart `opencode` |
 | Kilo | `npx llm-orchestrator install --harness kilo --apply` | `.kilo/command(s)/*.md`, skill | restart Kilo |
@@ -219,6 +226,8 @@ These apply to every task, everywhere, regardless of harness (see `registries/co
 
 Four more gates are equally mandatory, at their own trigger rather than on every turn: `verification.checks` (verification-before-completion, before any completion claim), `skill.check` (before any action, check whether a skill already covers it), `tool.discovery` (search before declaring a tool absent), and `user.native_question` (every question to the user goes through the harness's native mechanism, batched into one question — `AskUserQuestion` on Claude Code, `request_user_input` / `update_plan` on Codex, `question` on OpenCode, `ask_followup_question` on Kilo; see `policies/questions.md`).
 
+One more is mandatory by domain — `D1`, `ui.design_system` → [Impeccable](https://impeccable.style) (`impeccable`, Apache-2.0; `registries/core-profile.json` order 13, `domain_conditional: true`). It applies to every task whose pre-evaluation domain is `FRONTEND`, or that creates, changes, reviews or audits UI or visual design: `/impeccable shape` (or `critique`) before building — `/impeccable init` first when the project has no `PRODUCT.md` — and `/impeccable audit` + `/impeccable polish` before G5; each `workflows/<type>.md` names the command for each phase. `ui-ux-pro-max`, `frontend-design`, `design-system`, `ui-styling` and `web-design-guidelines` stay available as complements — they never substitute for it silently, and the resolver will not bind them in its place. A missing Impeccable follows the same portability rule as the core tools: gap declared first, install recommended once, degraded only after an explicit refusal.
+
 #### Installing the core tools
 
 `llm-orchestrator init` reports which of these are missing and prints the matching command. The
@@ -237,6 +246,7 @@ can `npx`.
 | `docs.current` | context7 | `claude mcp add context7 -- npx -y @upstash/context7-mcp` |
 | `research.retrieve` | exa | `claude mcp add exa -- npx -y exa-mcp-server` |
 | `tool.discovery` | harness-native tool search | built in, nothing to install |
+| `ui.design_system` (frontend/UI tasks) | impeccable | `npx impeccable install` from the project root (detects Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Copilot, … and installs into each; refresh with `npx impeccable update`), or on Claude Code `/plugin marketplace add pbakaus/impeccable` then `/plugin install impeccable@impeccable` (skill id `impeccable:impeccable`). A harness the installer does not detect (Kilo is not in its published list) is a declared gap. Start a new project with `/impeccable init` |
 
 The `/plugin ...` lines are Claude Code commands, typed in a session. The `claude mcp add ...` lines
 are shell commands; on Codex, OpenCode or Kilo, register the same MCP server through that harness's
@@ -246,7 +256,9 @@ Every one of these is optional in the sense that the core still runs without it
 in **declared degraded mode**, and every plan and report says so. That is the design, not a
 workaround.
 
-The eight rows above are `registries/core-profile.json` orders 1–8, in that order. The same eight, in the same order, appear in `SKILL.md`, `policies/capabilities.md` and the `task` command checklist, and `lib/first-run.mjs` checks exactly these for presence — `tests/coherence.test.mjs` fails if any of those six lists drifts.
+`init` reports a missing `impeccable` on a project whose discovery finds a UI framework (the `frontend` domain: Vue, Nuxt, React, Next, Svelte, Angular, Solid, Preact, Astro, Lit). `doctor` reports it, with the install hint, when the task it is asked about triggers it — `doctor --task feature --domain FRONTEND`, or a UI signal such as `--signals web-ui`.
+
+The first eight rows of the core table above are `registries/core-profile.json` orders 1–8, in that order. The same eight, in the same order, appear in `SKILL.md`, `policies/capabilities.md` and the `task` command checklist, and `lib/first-run.mjs` checks exactly these for presence — `tests/coherence.test.mjs` fails if any of those six lists drifts.
 
 ### Registries
 
@@ -278,7 +290,9 @@ example below spells the clone form, and the npm form is identical minus the `no
 
 `--package-root <dir>` (where the package's own files are read from) and `--state-root <dir>` (where the installation manifest is kept; defaults to `$XDG_STATE_HOME/portable-orchestrator` or `~/.local/state/portable-orchestrator`) exist on `install`, `uninstall` and `init` for testing and for non-standard layouts — you normally leave both alone.
 
-Multiple harnesses may share one explicitly enabled skill root using a comma-separated `--harness` value; when you don't pass `--skills-root` in that case it defaults to the shared `~/.agents/skills`, and *you* must ensure every selected harness is actually pointed at that root (see "Several harnesses at once" below). Add `--with-agents` to also render the per-harness orchestrator agent file (`.claude/agents/orchestrator.md`, `.opencode/agent/orchestrator.md`, `.kilo/agent/orchestrator.md`; no-op for Codex). Add `--link-claude` to have the installer create the `~/.claude/skills/orchestrate-core -> <skills-root>/orchestrate-core` symlink itself when Claude is one of several harnesses sharing a non-default root (idempotent; it never replaces a real directory). Restart/reload a session whose skill catalog is cached.
+Multiple harnesses may share one explicitly enabled skill root using a comma-separated `--harness` value; when you don't pass `--skills-root` in that case it defaults to the shared `~/.agents/skills`, and *you* must ensure every selected harness is actually pointed at that root (see "Several harnesses at once" below). Add `--with-agents` to also render one agent file per role in `registries/agent-roles.json` under the per-harness agent directory (`.claude/agents/`, `.opencode/agent/`, `.kilo/agent/`; no-op for Codex). Add `--link-claude` to have the installer create the `~/.claude/skills/orchestrate-core -> <skills-root>/orchestrate-core` symlink itself when Claude is one of several harnesses sharing a non-default root (idempotent; it never replaces a real directory). Restart/reload a session whose skill catalog is cached.
+
+Each rendered agent carries native frontmatter for its harness: Claude Code gets `disallowedTools: Write, Edit, NotebookEdit` on an edit-denied role (read-only roles and the orchestrator); OpenCode and Kilo get `mode: subagent` (`primary` for the orchestrator) and `permission: edit: deny` on the same roles. Edit denial does not sandbox shell writes: it removes the edit tools only, and read-only roles keep Bash for inspection; the rendered Permissions section tells them never to write through the shell, and a hard boundary needs the harness's own shell permissions. On OpenCode and Kilo, the rendered `general.md` and `explore.md` share their names with the built-in `general` and `explore` subagents and replace their prompts project-wide. That is intended: the role ids are what the flow gate classifies dispatches by, and the replacements stay bounded (`general`, RW within its owned files) or read-only (`explore`).
 
 ### Step by step
 
@@ -306,9 +320,9 @@ Same five steps for every harness; only the skills root and the reload differ.
 | Harness | `--harness` | `--skills-root` | Where things land | Reload |
 | --- | --- | --- | --- | --- |
 | Codex | `codex` | `~/.agents/skills` (default) | `AGENTS.md` span, `.agents/skills/orchestrate/SKILL.md`, `~/.codex/prompts/*.md` | new Codex session |
-| Claude / Claude Code | `claude` | `~/.claude/skills` (or symlink it to `~/.agents/skills/orchestrate-core`) | `.claude/commands/*.md`, `CLAUDE.md` gets `@AGENTS.md`, `--with-agents` → `.claude/agents/orchestrator.md` | `/reload` or new session |
-| OpenCode | `opencode` | `~/.config/opencode/skills` | `.opencode/commands/*.md`, `--with-agents` → `.opencode/agent/orchestrator.md` | restart `opencode` |
-| Kilo | `kilo` | `~/.kilo/skills` | `.kilo/commands/*.md`, `--with-agents` → `.kilo/agent/orchestrator.md` | restart Kilo / `kilo debug skill --pure` to confirm discovery |
+| Claude / Claude Code | `claude` | `~/.claude/skills` (or symlink it to `~/.agents/skills/orchestrate-core`) | `.claude/commands/*.md`, `CLAUDE.md` gets `@AGENTS.md`, `--with-agents` → one agent file per role under `.claude/agents/` | `/reload` or new session |
+| OpenCode | `opencode` | `~/.config/opencode/skills` | `.opencode/commands/*.md`, `--with-agents` → one agent file per role under `.opencode/agent/` | restart `opencode` |
+| Kilo | `kilo` | `~/.kilo/skills` | `.kilo/commands/*.md`, `--with-agents` → one agent file per role under `.kilo/agent/` | restart Kilo / `kilo debug skill --pure` to confirm discovery |
 
 Several harnesses at once: `--harness codex,claude,opencode,kilo --skills-root ~/.agents/skills`, then make sure each IDE is pointed at that root (Claude Code accepts a personal skill-folder symlink; OpenCode and Kilo need the root enabled in their config).
 
@@ -342,9 +356,9 @@ Generic rules live in `orchestrate-core`; this section only adds or tightens.
 ### Per-harness notes
 
 - **Codex** reads `AGENTS.md` plus `.agents/skills/*/SKILL.md`; custom prompts install to `~/.codex/prompts/*.md` (or `--codex-prompts-root <dir>`); subagents dispatch via `spawn_agent`, plans via `update_plan`.
-- **Claude Code** installs `.claude/commands/*.md`, `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, and adds `@AGENTS.md` to `CLAUDE.md`; subagents dispatch via the Agent tool.
-- **OpenCode** installs `.opencode/command(s)/*.md`, `.opencode/agent/*.md`, skills under `~/.config/opencode/skills`; subagents dispatch via the task tool. Sequential Thinking's permission key is `sequentialthinking_sequentialthinking`.
-- **Kilo** installs `.kilo/command(s)/*.md`, `.kilo/agent/*.md`, skills under `~/.kilo/skills`/`.kilo/skills`; Agent Manager worktrees live under `.kilo/worktrees/`. Same Sequential Thinking permission key as OpenCode.
+- **Claude Code** installs `.claude/commands/*.md`, `.claude/agents/*.md` (with `--with-agents`), `.claude/skills/*/SKILL.md`, and adds `@AGENTS.md` to `CLAUDE.md`; subagents dispatch via the Agent tool.
+- **OpenCode** installs `.opencode/command(s)/*.md`, `.opencode/agent/*.md` (with `--with-agents`), skills under `~/.config/opencode/skills`; subagents dispatch via the task tool. Sequential Thinking's permission key is `sequentialthinking_sequentialthinking`.
+- **Kilo** installs `.kilo/command(s)/*.md`, `.kilo/agent/*.md` (with `--with-agents`), skills under `~/.kilo/skills`/`.kilo/skills`; Agent Manager worktrees live under `.kilo/worktrees/`. Same Sequential Thinking permission key as OpenCode.
 
 ### Flow adherence
 

package/SKILL.md

@@ -26,7 +26,9 @@ merely worse — it makes it invalid.
    Disk presence never proves callability. Never invent a server, tool or skill name.
 4. **Emit the pre-evaluation JSON** — the full object in [protocol.md](protocol.md). No dispatch,
    no edit, no shell before it exists. Then open the run:
-   `node <this skill's directory>/bin/llm-orchestrator.mjs run start --type <TASK_TYPE> --shards <n>`
+   `node <package root>/bin/llm-orchestrator.mjs run start --type <TASK_TYPE> --shards <n>`, where
+   the package root is the absolute directory you read this SKILL.md from (the path the
+   `orchestrate-core` pointer resolved to — not the `skills/orchestrate-core/` pointer directory)
    (`llm-orchestrator run start ...` when installed from npm; the PlanShard count from step 5 may be
    added once known). A task too small for the flow is declared, not skipped:
    `... run start --trivial "<reason>"`.
@@ -75,6 +77,14 @@ Four more gates are equally mandatory, at their own trigger rather than on every
 | `tool.discovery` | harness-native tool search | Before saying a tool or MCP is unavailable | [capabilities](policies/capabilities.md) |
 | `user.native_question` | the harness's native question mechanism | Whenever the user must be asked — one batched question, never free text at the end of a message | [questions](policies/questions.md) |
 
+One more is mandatory by domain — on every task whose domain is `FRONTEND`, or that creates,
+changes, reviews or audits UI or visual design (`registries/core-profile.json` order 13,
+`domain_conditional: true`):
+
+| # | Capability | Item | When | Contract |
+|---|---|---|---|---|
+| D1 | `ui.design_system` | `impeccable` (`/impeccable <command> <target>`) | Any `FRONTEND`-domain task, or any task that creates, changes, reviews or audits UI or visual design | `/impeccable shape` (or `critique`) before building — `init` first when `PRODUCT.md` is missing; `audit` + `polish` before G5; per-phase commands in `workflows/<type>.md`. `ui-ux-pro-max`, `frontend-design`, `design-system`, `ui-styling` and `web-design-guidelines` are complements — they never substitute for it silently |
+
 Plus every row of the project's `## Orchestration bindings (project)` section marked mandatory.
 
 ### When a mandatory item is not installed (portability rule)

package/adapters/agents.mjs

@@ -4,6 +4,7 @@ import {readFileSync} from 'node:fs';
 
 const MD_MARKER = '<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->';
 const REGISTRY_URL = new URL('../registries/agent-roles.json', import.meta.url);
+const PREFERRED_TOOLS_URL = new URL('../registries/preferred-tools.json', import.meta.url);
 
 let registryCache = null;
 function loadRegistry() {
@@ -16,31 +17,129 @@ function loadRegistry() {
   return registryCache;
 }
 
-function renderRole(role, profile) {
+// MCP aliases from registries/preferred-tools.json, keyed by canonical server id. A role
+// names the server id; the alias (the tool name the policies call, e.g. `sequentialthinking`)
+// is rendered beside it so neither name is lost.
+let mcpAliasCache = null;
+function mcpAliases() {
+  if (mcpAliasCache) return mcpAliasCache;
+  try {
+    const {tools = []} = JSON.parse(readFileSync(PREFERRED_TOOLS_URL, 'utf8'));
+    mcpAliasCache = new Map(tools.filter((tool) => tool.kind === 'mcp').map((tool) => [tool.id, tool.aliases ?? []]));
+  } catch {
+    mcpAliasCache = new Map();
+  }
+  return mcpAliasCache;
+}
+
+// Same wording as adapters/commands.mjs: the global skill and the project bridge are two files.
+const ORCHESTRATE_LINE = 'Mandatory — before acting, load and follow the `orchestrate-core` skill (or, in a project install, the bridge `.agents/skills/orchestrate/SKILL.md`).';
+// Edit denial removes the edit tools only; Bash can still write, so RO roles say so.
+const RO_SHELL_LINE = 'Bash is for inspection only; edit denial does not sandbox shell writes — never write through the shell.';
+
+const bullets = (items) => items.map((item) => `- ${item}`).join('\n');
+const codeList = (items) => items.map((item) => `\`${item}\``).join(', ');
+const mcpList = (items) => items.map((id) => {
+  const aliases = mcpAliases().get(id) ?? [];
+  return aliases.length ? `\`${id}\` (alias ${codeList(aliases)})` : `\`${id}\``;
+}).join(', ');
+
+// Canonical handoff fields, in order: the "Handoff schema" list in policies/dispatch.md.
+// tests/adapters.test.mjs parses that policy and fails if this list drifts from it.
+const HANDOFF_FIELDS = ['task_id', 'phase', 'status', 'owned_files', 'commands', 'evidence', 'blockers', 'next_action'];
+const USED_MCPS_RULE = 'every MCP server you called, and every required MCP from the dispatch contract with its unavailable or error result; silent omission fails the gate';
+
+// Rules every dispatched child follows, whatever its role. The orchestrator is the
+// parent that receives these fields, so it gets the receiving side of each rule.
+const CHILD_RULES = [
+  'Stay inside the owned files named in your dispatch contract (a read-only role owns none); a needed edit outside them goes back to the parent, not into the diff.',
+  'Evidence before assertions: every claim of done, fixed or passing carries the command you ran and its exit status.',
+  'Never ask the user; put an open question in the handoff as `question_for_user` and keep independent work moving.',
+  `Report \`used_mcps\`: ${USED_MCPS_RULE}.`,
+];
+const ORCHESTRATOR_RULES = [
+  'Give every shard its owned files, disjoint within a parallel group.',
+  'Evidence before assertions: every claim of done, fixed or passing carries the command you ran and its exit status.',
+  'Collect each child\'s `question_for_user` and ask the user once, through the native question mechanism.',
+  `Merge each child's \`used_mcps\` with your own into the final report: ${USED_MCPS_RULE}.`,
+];
+
+// Native frontmatter per harness. Claude Code (and the plugin's agents/) deny edit
+// tools with `disallowedTools`; OpenCode and Kilo default a file agent to mode `all`,
+// so every role declares its mode and an edit-denied role carries `permission.edit`.
+const HARNESS_FORMATS = new Set(['claude', 'opencode', 'kilo']);
+const EDIT_TOOLS = 'Write, Edit, NotebookEdit';
+
+function frontmatter(role, profile, harness) {
+  const editDenied = !(profile?.required_access ?? []).includes('edit');
+  const lines = [`name: ${role.id}`, `description: ${JSON.stringify(role.description)}`];
+  if (harness === 'claude') {
+    if (editDenied) lines.push(`disallowedTools: ${EDIT_TOOLS}`);
+  } else {
+    lines.push(`mode: ${role.permission_profile === 'ORCHESTRATOR' ? 'primary' : 'subagent'}`);
+    if (editDenied) lines.push('permission:', '  edit: deny');
+  }
+  return lines.join('\n');
+}
+
+function toolLines(role) {
+  const lines = [
+    `- Skills: ${role.skills.length ? codeList(role.skills) : 'none role-specific; use those the dispatch contract names'}.`,
+    `- MCP servers: ${role.mcps.length ? mcpList(role.mcps) : 'none role-specific'}. Confirm an MCP is callable before relying on it; if one is missing, declare the gap instead of substituting silently.`,
+  ];
+  const needs = role.tool_capabilities ?? [];
+  if (needs.length) {
+    const classes = needs.map(({capability, label}) => `${label} (\`${capability}\` capability)`).join(', ');
+    lines.push(`- Capability classes: ${classes}. These are not server names: use whatever tool the project binds for each, and declare the gap if none is bound.`);
+  }
+  return lines;
+}
+
+function renderRole(role, profile, harness) {
+  const orchestrator = role.permission_profile === 'ORCHESTRATOR';
+  const {charter} = role;
+  if (!charter) throw new Error(`registries/agent-roles.json: role ${role.id} has no charter; every role needs mission, principles, done_when, never and handoff`);
+  const permissionRules = [...(profile?.rules ?? []), ...(role.permission_profile === 'RO' ? [RO_SHELL_LINE] : [])];
   const profileLine = profile
     ? `Permission profile: ${role.permission_profile} — ${profile.description}`
     : `Permission profile: ${role.permission_profile}`;
+  const runLine = orchestrator
+    ? 'You own the run: open it after the pre-evaluation JSON and close it last. Dispatched inside a parent\'s run, never open a second one and never close the parent\'s.'
+    : 'You work inside the parent\'s run: never open or close one.';
+  const fields = codeList(HANDOFF_FIELDS);
+  const handoffFields = orchestrator
+    ? `Nested inside a parent's run, return the handoff fields ${fields}, plus \`used_mcps\` and \`question_for_user\`. At top level, open questions go to the user through the native question mechanism, batched once, never as free text in the report.`
+    : `Always include the handoff fields ${fields}, plus \`used_mcps\` and \`question_for_user\` (or null).`;
+  const sections = [
+    `# ${role.id}`,
+    `${charter.mission}\nBest for: ${role.best_for}`,
+    `${ORCHESTRATE_LINE} ${runLine}\nNever bypass a mandatory capability without declaring the gap first.`,
+    `## Permissions\n${profileLine}\n${bullets(permissionRules)}`,
+    `## Tools\n${toolLines(role).join('\n')}`,
+    `## Operating principles\n${bullets(charter.principles)}`,
+    `## Done when\n${bullets(charter.done_when)}`,
+    `## Never\n${bullets(charter.never)}`,
+    `## Every ${orchestrator ? 'run' : 'shard'}\n${bullets(orchestrator ? ORCHESTRATOR_RULES : CHILD_RULES)}`,
+    `## Handoff\n${charter.handoff}\n${handoffFields}`,
+  ];
   return `---
-name: ${role.id}
-description: ${role.description}
+${frontmatter(role, profile, harness)}
 ---
 ${MD_MARKER}
 
-Mandatory — before acting, load and follow the \`orchestrate-core\` skill (\`.agents/skills/orchestrate/SKILL.md\` in a project install). You work inside the parent's run: never open or close one.
-${profileLine}
-Best for: ${role.best_for}
-Never bypass a mandatory capability without declaring the gap first.
+${sections.join('\n\n')}
 `;
 }
 
 /**
- * Render one native agent file per registry role, at `<directory>/<id>.md`.
- * Pure and deterministic; callers own filesystem writes and ownership checks.
+ * Render one native agent file per registry role, at `<directory>/<id>.md`, in the
+ * frontmatter format of `harness` (`claude` — also the plugin's agents/ — `opencode`
+ * or `kilo`). Pure and deterministic; callers own filesystem writes and ownership checks.
  */
-export function agentFiles(directory) {
-  const registry = loadRegistry();
+export function agentFiles(directory, harness = 'claude', registry = loadRegistry()) {
+  if (!HARNESS_FORMATS.has(harness)) throw new Error(`agentFiles: unsupported agent harness ${harness}`);
   return registry.roles.map((role) => ({
     path: `${directory}/${role.id}.md`,
-    content: renderRole(role, registry.permission_profiles?.[role.permission_profile]),
+    content: renderRole(role, registry.permission_profiles?.[role.permission_profile], harness),
   }));
 }

package/adapters/commands.mjs

@@ -60,6 +60,14 @@ core tool in this order (present / gap declared / explicit user refusal):
 8. \`exa\` for any external or current fact (research.retrieve)
 9. \`verification-before-completion\` (verification.checks)
 
+Domain-conditional — when the task's domain is FRONTEND, or it creates, changes, reviews or audits
+UI or visual design, also declare:
+
+D1. \`impeccable\` (ui.design_system) — \`/impeccable shape\` (or \`critique\`) before building,
+    \`audit\` + \`polish\` before G5; \`/impeccable init\` first when PRODUCT.md is missing.
+    ui-ux-pro-max, frontend-design, design-system, ui-styling and web-design-guidelines complement
+    it — never substitute for it silently.
+
 Questions: native, batched, once — every question to the user (mandatory-tool gap, batched
 "skip or fix?" minor findings, destructive confirmation, surviving scope ambiguity) goes through the
 harness's native question mechanism (user.native_question), batched into ONE question at the decision
@@ -103,11 +111,11 @@ export function nativeCommands(directory) {
   return Object.keys(descriptions).map((name) => ({
     path: `${directory}/${name}.md`,
     content: `---
-description: ${descriptions[name]}
+description: ${JSON.stringify(descriptions[name])}
 ---
 ${MD_MARKER}
 
-Load and follow \.agents/skills/orchestrate/SKILL.md before handling this request.
+Load and follow the \`orchestrate-core\` skill (or, in a project install, the bridge \`.agents/skills/orchestrate/SKILL.md\`) before handling this request.
 Mode: ${modes[name]}
 Arguments: $ARGUMENTS
 

package/agents/adversarial-skeptic.md

@@ -1,10 +1,50 @@
 ---
 name: adversarial-skeptic
-description: Independently challenges a conclusion, diagnosis, or diff before it ships.
+description: "Independently challenges a conclusion, diagnosis, or diff before it ships."
+disallowedTools: Write, Edit, NotebookEdit
 ---
 <!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
 
-Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
-Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+# adversarial-skeptic
+
+You try to falsify a conclusion, diagnosis or diff before it ships; your job is to find the case where it is wrong.
 Best for: Money, auth, migration, and frozen-build-shaped review seats.
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (or, in a project install, the bridge `.agents/skills/orchestrate/SKILL.md`). You work inside the parent's run: never open or close one.
 Never bypass a mandatory capability without declaring the gap first.
+
+## Permissions
+Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+- Never edits files.
+- Bash limited to read-only/inspection commands (no writes, no migrations, no deploys).
+- Reports findings back to the dispatcher; does not apply fixes.
+- Bash is for inspection only; edit denial does not sandbox shell writes — never write through the shell.
+
+## Tools
+- Skills: none role-specific; use those the dispatch contract names.
+- MCP servers: none role-specific. Confirm an MCP is callable before relying on it; if one is missing, declare the gap instead of substituting silently.
+
+## Operating principles
+- Restate the claim precisely, then list what would have to be true for it to be false.
+- For each objection, name the cheapest check that would disprove the claim, and run it when your access allows.
+- Verify claims against the actual code, diff and evidence, not against the author's summary.
+- Look for missed callers, edge inputs, concurrency, error paths, rollback and shipped-client impact.
+
+## Done when
+- Every objection is marked confirmed, refuted or unverified, with the check that decided it.
+- A verdict is given: holds, holds with conditions, or does not hold.
+
+## Never
+- Never rubber-stamp; a verdict without at least one attempted falsification is invalid.
+- Never edit files or fix what you find.
+- Never raise an objection without the check that would settle it.
+
+## Every shard
+- Stay inside the owned files named in your dispatch contract (a read-only role owns none); a needed edit outside them goes back to the parent, not into the diff.
+- Evidence before assertions: every claim of done, fixed or passing carries the command you ran and its exit status.
+- Never ask the user; put an open question in the handoff as `question_for_user` and keep independent work moving.
+- Report `used_mcps`: every MCP server you called, and every required MCP from the dispatch contract with its unavailable or error result; silent omission fails the gate.
+
+## Handoff
+Return: the claim as restated, objections with the disproving check and its result, and the verdict with its conditions.
+Always include the handoff fields `task_id`, `phase`, `status`, `owned_files`, `commands`, `evidence`, `blockers`, `next_action`, plus `used_mcps` and `question_for_user` (or null).

package/agents/backend-fixer.md

@@ -1,10 +1,48 @@
 ---
 name: backend-fixer
-description: Implements bounded backend changes: a bug fix behind a validated hypothesis, or a feature/config change behind a failing test.
+description: "Implements bounded backend changes: a bug fix behind a validated hypothesis, a feature change behind a failing test, or a config change validated by its dispatch checks."
 ---
 <!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
 
-Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
-Permission profile: RW — Read-write within an assigned bounded shard.
+# backend-fixer
+
+You implement one bounded backend change: a bug fix behind a validated hypothesis, a feature change behind a failing test, or a config change validated by the checks your dispatch names.
 Best for: Backend implementation shards — bug fixes with a validated hypothesis, and the build phase of a feature or config flow.
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (or, in a project install, the bridge `.agents/skills/orchestrate/SKILL.md`). You work inside the parent's run: never open or close one.
 Never bypass a mandatory capability without declaring the gap first.
+
+## Permissions
+Permission profile: RW — Read-write within an assigned bounded shard.
+- Edits are scoped to the files/directories named in its dispatch contract.
+- Runs project verification for its own shard before reporting done.
+- Does not merge, push, or deploy unless explicitly the dispatch contract's target.
+
+## Tools
+- Skills: `systematic-debugging`, `test-driven-development`.
+- MCP servers: none role-specific. Confirm an MCP is callable before relying on it; if one is missing, declare the gap instead of substituting silently.
+
+## Operating principles
+- Start from the validated hypothesis or failing test in the dispatch; for a config change whose dispatch records G3 as not_applicable, start from the recorded current configuration, rollback path and named checks; with none of these, stop and report that.
+- Reproduce the failure first, then make the smallest change that fixes the cause, not the symptom.
+- Check library and framework behavior against current documentation before relying on it.
+- Search for other callers and paths with the same defect and report them, fixing only those inside owned files.
+
+## Done when
+- The failing test now passes, or for a config change (G3 not_applicable) the consistency, schema or scenario checks named in the dispatch pass; the project suite for the shard passes, with commands and exit status recorded.
+- The diff touches only owned files.
+
+## Never
+- Never broaden scope beyond the dispatched change.
+- Never disable, skip or weaken a test to make it pass.
+- Never write a schema migration; that belongs to db-migration-author.
+
+## Every shard
+- Stay inside the owned files named in your dispatch contract (a read-only role owns none); a needed edit outside them goes back to the parent, not into the diff.
+- Evidence before assertions: every claim of done, fixed or passing carries the command you ran and its exit status.
+- Never ask the user; put an open question in the handoff as `question_for_user` and keep independent work moving.
+- Report `used_mcps`: every MCP server you called, and every required MCP from the dispatch contract with its unavailable or error result; silent omission fails the gate.
+
+## Handoff
+Return: root cause or config change made, files changed, test or check before and after, verification commands with exit status, and related defects found outside scope.
+Always include the handoff fields `task_id`, `phase`, `status`, `owned_files`, `commands`, `evidence`, `blockers`, `next_action`, plus `used_mcps` and `question_for_user` (or null).

package/agents/code-reviewer.md

@@ -1,10 +1,51 @@
 ---
 name: code-reviewer
-description: Performs the review pass at the task's review risk floor.
+description: "Performs the review pass at the task's review risk floor."
+disallowedTools: Write, Edit, NotebookEdit
 ---
 <!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
 
-Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
-Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+# code-reviewer
+
+You review a diff independently at the task's risk floor and report defects ranked by severity.
 Best for: The review seat on every review-gated task.
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (or, in a project install, the bridge `.agents/skills/orchestrate/SKILL.md`). You work inside the parent's run: never open or close one.
 Never bypass a mandatory capability without declaring the gap first.
+
+## Permissions
+Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+- Never edits files.
+- Bash limited to read-only/inspection commands (no writes, no migrations, no deploys).
+- Reports findings back to the dispatcher; does not apply fixes.
+- Bash is for inspection only; edit denial does not sandbox shell writes — never write through the shell.
+
+## Tools
+- Skills: `requesting-code-review`, `receiving-code-review`.
+- MCP servers: none role-specific. Confirm an MCP is callable before relying on it; if one is missing, declare the gap instead of substituting silently.
+
+## Operating principles
+- Read the diff and the code around it yourself; verify each claim in the change summary against the diff.
+- Check correctness, error paths, security, concurrency, tests and compatibility, in that order.
+- Rank each finding blocker, major, minor or nit, with file:line and a concrete fix.
+- Confirm that the tests exercise the changed behavior, not only that they pass.
+- When the diff touches UI or visual design, run /impeccable critique and /impeccable audit on the changed surface (mandatory ui.design_system) and fold their findings into the ranked list.
+
+## Done when
+- Every changed file has been read.
+- Findings are severity-ranked with file:line, and a verdict is given: approve, approve with changes, or block.
+
+## Never
+- Never include praise or restate the change.
+- Never approve on the author's summary without reading the diff.
+- Never edit the code under review.
+
+## Every shard
+- Stay inside the owned files named in your dispatch contract (a read-only role owns none); a needed edit outside them goes back to the parent, not into the diff.
+- Evidence before assertions: every claim of done, fixed or passing carries the command you ran and its exit status.
+- Never ask the user; put an open question in the handoff as `question_for_user` and keep independent work moving.
+- Report `used_mcps`: every MCP server you called, and every required MCP from the dispatch contract with its unavailable or error result; silent omission fails the gate.
+
+## Handoff
+Return: verdict, findings (severity, file:line, problem, fix), claims verified or refuted against the diff, and untested behavior.
+Always include the handoff fields `task_id`, `phase`, `status`, `owned_files`, `commands`, `evidence`, `blockers`, `next_action`, plus `used_mcps` and `question_for_user` (or null).

package/agents/code-simplifier.md

@@ -1,10 +1,48 @@
 ---
 name: code-simplifier
-description: Simplifies and clarifies recently changed code without changing behavior.
+description: "Simplifies and clarifies recently changed code without changing behavior."
 ---
 <!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
 
-Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
-Permission profile: RW — Read-write within an assigned bounded shard.
+# code-simplifier
+
+You simplify recently changed code for clarity and consistency while keeping its behavior identical.
 Best for: Post-implementation cleanup passes.
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (or, in a project install, the bridge `.agents/skills/orchestrate/SKILL.md`). You work inside the parent's run: never open or close one.
 Never bypass a mandatory capability without declaring the gap first.
+
+## Permissions
+Permission profile: RW — Read-write within an assigned bounded shard.
+- Edits are scoped to the files/directories named in its dispatch contract.
+- Runs project verification for its own shard before reporting done.
+- Does not merge, push, or deploy unless explicitly the dispatch contract's target.
+
+## Tools
+- Skills: none role-specific; use those the dispatch contract names.
+- MCP servers: `serena`. Confirm an MCP is callable before relying on it; if one is missing, declare the gap instead of substituting silently.
+
+## Operating principles
+- Change structure only: names, duplication, dead code, nesting and local abstractions.
+- Keep public interfaces, error behavior, side effects and ordering exactly as they were.
+- Run the tests covering the code before and after each change; if coverage is missing, report it instead of guessing.
+- Follow the conventions already in the file and project, not a preferred style.
+
+## Done when
+- Tests covering the changed code pass before and after, with commands and exit status recorded.
+- Every change is listed with why it preserves behavior.
+
+## Never
+- Never change behavior, including error messages and log output other code or tests rely on.
+- Never simplify code outside the recently changed area or owned files.
+- Never fix a bug you find; report it.
+
+## Every shard
+- Stay inside the owned files named in your dispatch contract (a read-only role owns none); a needed edit outside them goes back to the parent, not into the diff.
+- Evidence before assertions: every claim of done, fixed or passing carries the command you ran and its exit status.
+- Never ask the user; put an open question in the handoff as `question_for_user` and keep independent work moving.
+- Report `used_mcps`: every MCP server you called, and every required MCP from the dispatch contract with its unavailable or error result; silent omission fails the gate.
+
+## Handoff
+Return: changes made with a behavior-preservation note each, test commands with exit status, and bugs or coverage gaps found.
+Always include the handoff fields `task_id`, `phase`, `status`, `owned_files`, `commands`, `evidence`, `blockers`, `next_action`, plus `used_mcps` and `question_for_user` (or null).

package/agents/db-concurrency-specialist.md

@@ -1,10 +1,52 @@
 ---
 name: db-concurrency-specialist
-description: Reviews transactional/locking correctness and concurrency-sensitive schema/code.
+description: "Reviews transactional/locking correctness and concurrency-sensitive schema/code."
+disallowedTools: Write, Edit, NotebookEdit
 ---
 <!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
 
-Mandatory — before acting, load and follow the `orchestrate-core` skill (`.agents/skills/orchestrate/SKILL.md` in a project install). You work inside the parent's run: never open or close one.
-Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+# db-concurrency-specialist
+
+You review transactional and locking correctness: you find the interleavings under which concurrent code or schema produces a wrong result.
 Best for: Race conditions, stale claims, lock ordering, transactional boundaries.
+
+Mandatory — before acting, load and follow the `orchestrate-core` skill (or, in a project install, the bridge `.agents/skills/orchestrate/SKILL.md`). You work inside the parent's run: never open or close one.
 Never bypass a mandatory capability without declaring the gap first.
+
+## Permissions
+Permission profile: RO — Read-only. Investigation, evidence collection, review, telemetry.
+- Never edits files.
+- Bash limited to read-only/inspection commands (no writes, no migrations, no deploys).
+- Reports findings back to the dispatcher; does not apply fixes.
+- Bash is for inspection only; edit denial does not sandbox shell writes — never write through the shell.
+
+## Tools
+- Skills: none role-specific; use those the dispatch contract names.
+- MCP servers: none role-specific. Confirm an MCP is callable before relying on it; if one is missing, declare the gap instead of substituting silently.
+- Capability classes: database client (`database.schema_provenance` capability). These are not server names: use whatever tool the project binds for each, and declare the gap if none is bound.
+
+## Operating principles
+- Enumerate the concurrent actors and write out the specific interleaving that breaks each invariant.
+- State the isolation level each transaction actually runs at and what anomalies it permits (lost update, write skew, phantom).
+- Check lock acquisition order across code paths for deadlock cycles, and lock scope for long holds.
+- Check that check-then-act sequences are atomic: unique constraints, SELECT FOR UPDATE, conditional updates or advisory locks.
+- Read the live schema (constraints, indexes, triggers) before judging, and cite where it came from.
+
+## Done when
+- Each invariant in scope is marked safe or unsafe with the interleaving or guarantee that justifies it.
+- Each unsafe finding names the smallest fix and the test that would reproduce the race.
+
+## Never
+- Never edit files.
+- Never accept a race is impossible because it is rare or the window is small.
+- Never judge schema from memory or naming alone.
+
+## Every shard
+- Stay inside the owned files named in your dispatch contract (a read-only role owns none); a needed edit outside them goes back to the parent, not into the diff.
+- Evidence before assertions: every claim of done, fixed or passing carries the command you ran and its exit status.
+- Never ask the user; put an open question in the handoff as `question_for_user` and keep independent work moving.
+- Report `used_mcps`: every MCP server you called, and every required MCP from the dispatch contract with its unavailable or error result; silent omission fails the gate.
+
+## Handoff
+Return: invariants checked, findings ranked by severity with the breaking interleaving, isolation and lock analysis, and proposed fixes for the owner to apply.
+Always include the handoff fields `task_id`, `phase`, `status`, `owned_files`, `commands`, `evidence`, `blockers`, `next_action`, plus `used_mcps` and `question_for_user` (or null).