llm-orchestrator 1.0.4 → 1.0.6

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.0.4",
+  "version": "1.0.6",
   "author": {
     "name": "Bogdan-Gabriel Torcescu",
     "url": "https://www.linkedin.com/in/bogdantorcescu/"

package/README.md

@@ -282,7 +282,7 @@ Same five steps for every harness; only the skills root and the reload differ.
    node bin/llm-orchestrator.mjs install --project /path/to/app --harness <harness>
    ```
 3. **Apply** the same command with `--apply`. Re-running is idempotent; a file you edited by hand is reported as a conflict, never overwritten.
-4. **Add project bindings** to `/path/to/app/AGENTS.md` (template below, or run `init --apply` to append it automatically when the section is missing). The core reads this section on every task; without it the core still runs with its generic matrix.
+4. **Add project bindings** to `/path/to/app/AGENTS.md` (template below, or run `init --apply` to append it automatically when the section is missing). `install` reports `bindings.present` and, when false, the exact `init --apply` command. The core reads this section on every task; without it the core still runs with its generic matrix.
 5. **Verify and reload**: `node bin/llm-orchestrator.mjs doctor --project /path/to/app --harness <harness>` must list every mandatory core tool as `present` (or as a declared gap with an install hint). Then reload the harness session so the skill catalog is refreshed.
 
 `node bin/llm-orchestrator.mjs init --project /path/to/app` runs steps 2, 4 (report only) and 5 together, before you commit to a harness — it proposes `--harness` from what it detects, shows the same dry-run plan, and lists exactly which of the 8 mandatory tools are missing with an install command for each.

package/bin/install.mjs

@@ -39,7 +39,15 @@ try {
     if (options.apply && options.linkClaude && (!result.conflicts || result.conflicts.length === 0) && options.harnesses.includes('claude')) {
       claudeSymlink = await linkClaudeSkillsRoot(options.skillsRoot);
     }
-    process.stdout.write(`${JSON.stringify({...result, files: result.files?.map(({absolutePath, content, ...file}) => file), ...(claudeSymlink ? {claudeSymlink} : {})}, null, 2)}\n`);
+    // `install` never writes the project bindings section — only `init --apply`
+    // does — so say so here, or a user who only ever runs `install` never learns
+    // the section exists and the core runs on its generic matrix forever.
+    const {agentsMdHasBindings, cliInvocation, BINDINGS_HEADING} = await import('../lib/first-run.mjs');
+    const bindingsPresent = await agentsMdHasBindings(options.project);
+    const bindings = bindingsPresent
+      ? {present: true}
+      : {present: false, section: BINDINGS_HEADING, next: `${cliInvocation()} init --project ${options.project} --apply`};
+    process.stdout.write(`${JSON.stringify({...result, files: result.files?.map(({absolutePath, content, ...file}) => file), ...(claudeSymlink ? {claudeSymlink} : {}), bindings}, null, 2)}\n`);
     if (result.conflicts?.length) process.exitCode = 2;
   }
 } catch (error) {

package/lib/first-run.mjs

@@ -197,7 +197,7 @@ Generic rules live in \`orchestrate-core\`; this section only adds or tightens.
 **Agent defaults:** \`<role>\` → \`<tier>\` (W T0–T1 / S T2 / S T3 / X T3 …).
 `;
 
-async function agentsMdHasBindings(project) {
+export async function agentsMdHasBindings(project) {
   try {
     const text = await readFile(join(project, 'AGENTS.md'), 'utf8');
     return text.includes(BINDINGS_HEADING);
@@ -215,8 +215,10 @@ async function agentsMdHasBindings(project) {
  * clone, the bare bin name when installed from npm (global or `npx`).
  */
 export function cliInvocation(argv = process.argv) {
+  // The unified CLI forwards by rewriting argv[1] to the subcommand script, so
+  // any script under this checkout's bin/ counts as "run from the clone".
   const script = argv[1] ? resolve(argv[1]) : '';
-  const fromClone = script === resolve(process.cwd(), 'bin', 'llm-orchestrator.mjs');
+  const fromClone = script.startsWith(resolve(process.cwd(), 'bin') + '/');
   return fromClone ? 'node bin/llm-orchestrator.mjs' : 'llm-orchestrator';
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-orchestrator",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "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.",
   "type": "module",
   "engines": {

package/policies/capabilities.md

@@ -40,9 +40,9 @@ README.
 | Task type | Mandatory | Optional (trigger) | Available |
 |---|---|---|---|
 | **INCIDENT** | `incident-start` → `-evidence` → `-fix` → `-verify` → `-close`, in that order; telemetry collection **before any hypothesis** | edge/CDN observability MCP (edge or worker symptom); native-platform debugger skill (native crash); memory recall of a prior incident (the symptom rhymes) | incident orchestration workflow, adversarial-skeptic |
-| **FEATURE** | brainstorming before plan mode; the test-engineer writes the **failing test first** | `context7` (any library/SDK API surface — even familiar ones); design-system + UI-styling skills (any new UI); payment-provider best-practices skill (money path); semantic-code MCP such as `serena` (large cross-file edit) | code-architect role, spec-complete code generator (only when the spec is complete and no clarification is needed) |
+| **FEATURE** | brainstorming before plan mode; the test-engineer writes the **failing test first** | `context7` (any library/SDK API surface — even familiar ones); design-system + UI-styling skills (any new UI); payment-provider best-practices skill (money path); semantic-code MCP such as `serena` (large cross-file edit) | `feature-dev-code-architect` (a harness-provided planning agent, not a core role), spec-complete code generator (only when the spec is complete and no clarification is needed) |
 | **BUG_FIX** | systematic-debugging; **reproduce before fixing** | route-data-flow-tracer (symptom crosses layers); db-concurrency-specialist (interleaving suspected); browser automation such as `playwright` (UI-visible) | compact investigator scout, read-only exploration agent |
-| **REFACTOR** | coverage exists **before the first edit** | code-simplifier; semantic-code MCP (symbol-level moves across many files) | bounded ≤2-file builder, code-explorer |
+| **REFACTOR** | coverage exists **before the first edit** | code-simplifier; semantic-code MCP (symbol-level moves across many files) | bounded ≤2-file builder, the `explore` role |
 | **INVESTIGATION** | adversarial challenge of the synthesis — never ship a single-source conclusion; **`exa` whenever any part of the explanation rests on external or current facts** | semantic-code MCP; memory recall before fanning out (the answer may already be filed) | read-only exploration agent, general-purpose agent |
 | **DEPLOY** | client-compatibility check + migrations applied + smoke; telemetry collection on the soak | native-build MCP (mobile/native build); CI/build MCP (edge or worker deploy); platform-config MCP (a third-party app config was touched) | performance profiling skills |
 | **CONFIG** | db-migration-author for **any schema change** — never hand-write a migration | provider-webhook-specialist (payment or store webhook); platform-config MCP; provider SDK upgrade skill | infrastructure API MCPs |

package/protocol.md

@@ -99,7 +99,7 @@ shards only. See [dispatch](policies/dispatch.md) and [routing](policies/routing
 | Type | Triggers | Flow | Core agent roles |
 |---|---|---|---|
 | **INCIDENT** | production error, 5xx, stuck state, webhook failure, alert | Evidence → Hypothesis → Fix → Verify → Close | production-telemetry-collector ×N + route-data-flow-tracer → adversarial-skeptic → builders → code-reviewer |
-| **FEATURE** | "build", "add", "create", "implement" | Plan → TDD → Build → Test → Review → Verify | planner → test-engineer → backend-fixer / frontend-fixer → code-reviewer |
+| **FEATURE** | "build", "add", "create", "implement" | Plan → TDD → Build → Test → Review → Verify | orchestrator → test-engineer → backend-fixer / frontend-fixer → code-reviewer |
 | **BUG_FIX** | "fix", "repair", "broken" | Reproduce → Evidence → Hypothesis → Regression → Fix → Review | investigation → test-engineer → builders → code-reviewer |
 | **REFACTOR** | "refactor", "clean up", "extract", "simplify" | Analyze → Coverage → Incremental → Review | code-simplifier → test-engineer → builders → code-reviewer |
 | **INVESTIGATION** | "why", "analyze", "how does", "debug" | Evidence → Synthesis → Challenge → Report | evidence collectors ×N → synthesizer → adversarial-skeptic |

package/registries/agent-roles.json

@@ -1 +1,370 @@
-{"_attribution":"llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving","version":1,"permission_profiles":{"RO":{"description":"Read-only. Investigation, evidence collection, review, telemetry.","required_access":["read","grep","glob","bash_readonly"],"rules":["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."]},"RW":{"description":"Read-write within an assigned bounded shard.","required_access":["read","grep","glob","edit","write","bash"],"rules":["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."]},"ORCHESTRATOR":{"description":"Plans, dispatches, and integrates; owns the overall session state.","required_access":["read","grep","glob","edit","write","bash","agent_dispatch"],"rules":["Never bypasses a mandatory capability without declaring the gap first.","Owns fan-out sizing, shard boundaries, and integration/merge order.","Runs final verification before reporting completion to the user."]}},"roles":[{"id":"orchestrator","description":"Plans work, resolves capabilities, dispatches bounded shards, integrates results.","capabilities":["orchestration.bootstrap","memory.recall","memory.checkpoint","workflow.selection","delegation.bounded"],"skills":["using-superpowers","brainstorming","dispatching-parallel-agents","subagent-driven-development"],"mcps":["sequential-thinking","mempalace"],"best_for":"Any nontrivial task needing more than one shard or a risk-floor review seat.","permission_profile":"ORCHESTRATOR","default_tier":"S T3"},{"id":"production-telemetry-collector","description":"Collects production logs/metrics/traces before an incident hypothesis is formed.","capabilities":["incident.telemetry_first"],"skills":["incident-orchestration","incident-evidence"],"mcps":[],"best_for":"Incident evidence gathering; never forms a fix on its own.","permission_profile":"RO","default_tier":"W T0-T1"},{"id":"route-data-flow-tracer","description":"Traces a request/data path across layers (frontend, API, DB, provider) read-only.","capabilities":["code.locate"],"skills":[],"mcps":["serena"],"best_for":"Symptoms that cross architectural layers.","permission_profile":"RO","default_tier":"W T0-T1"},{"id":"explore","description":"Read-only breadth search across a codebase: where something is defined, what calls it, which files are involved.","capabilities":["code.locate","tool.discovery"],"skills":[],"mcps":[],"best_for":"Broad read-only location work before a decision; never edits.","permission_profile":"RO","default_tier":"W T0-T1"},{"id":"db-concurrency-specialist","description":"Reviews transactional/locking correctness and concurrency-sensitive schema/code.","capabilities":["concurrency.review","database.schema_provenance"],"skills":[],"mcps":["db-client"],"best_for":"Race conditions, stale claims, lock ordering, transactional boundaries.","permission_profile":"RO","default_tier":"X T3","review_floor":"X T4"},{"id":"frontend-specialist","description":"Implements frontend changes that touch shared state, realtime or a native bridge, respecting shipped-client compatibility.","capabilities":["ui.design_system","test.behavioral"],"skills":["frontend-design","design-system"],"mcps":["playwright"],"best_for":"Complex frontend state, realtime surfaces and native-bridge implementation work.","permission_profile":"RW","default_tier":"S T3"},{"id":"provider-webhook-specialist","description":"Implements and reviews payment/webhook provider integrations (Stripe, Apple, Google).","capabilities":["billing.provider_evidence","push.provider_evidence","review.independent"],"skills":["stripe-best-practices"],"mcps":["billing-provider-api","push-provider-api"],"best_for":"Webhook signature/idempotency, provider state reconciliation, refund delivery.","permission_profile":"RW","default_tier":"X T2","review_floor":"X T4"},{"id":"adversarial-skeptic","description":"Independently challenges a conclusion, diagnosis, or diff before it ships.","capabilities":["review.adversarial","review.independent"],"skills":[],"mcps":[],"best_for":"Money, auth, migration, and frozen-build-shaped review seats.","permission_profile":"RO","default_tier":"S T3","review_floor":"X T4"},{"id":"test-engineer","description":"Writes and maintains behavioral/regression tests.","capabilities":["test.behavioral","workflow.tdd"],"skills":["test-driven-development"],"mcps":[],"best_for":"Coverage gaps, regression tests for bug fixes, refactor safety nets.","permission_profile":"RW","default_tier":"S T2"},{"id":"db-migration-author","description":"Sole authority for authoring SQL schema migrations.","capabilities":["config.migration_author","database.migration_checks","database.schema_provenance"],"skills":[],"mcps":["db-client"],"best_for":"Any new migration file; never hand-write one outside this role.","permission_profile":"RW","default_tier":"S T3","review_floor":"X T4"},{"id":"backend-fixer","description":"Implements backend bug fixes following systematic-debugging evidence.","capabilities":["workflow.debug","test.behavioral"],"skills":["systematic-debugging"],"mcps":[],"best_for":"Backend bug fixes with a validated hypothesis.","permission_profile":"RW","default_tier":"S T2"},{"id":"frontend-fixer","description":"Implements frontend bug fixes following systematic-debugging evidence.","capabilities":["workflow.debug","test.behavioral","ui.design_system"],"skills":["systematic-debugging"],"mcps":["playwright"],"best_for":"Frontend/UI bug fixes with a validated hypothesis.","permission_profile":"RW","default_tier":"S T2"},{"id":"code-simplifier","description":"Simplifies and clarifies recently changed code without changing behavior.","capabilities":["refactor.preservation","code.semantic_edit"],"skills":[],"mcps":["serena"],"best_for":"Post-implementation cleanup passes.","permission_profile":"RW","default_tier":"S T2"},{"id":"code-reviewer","description":"Performs the review pass at the task's review risk floor.","capabilities":["review.independent","workflow.review"],"skills":["requesting-code-review","receiving-code-review"],"mcps":[],"best_for":"The review seat on every review-gated task.","permission_profile":"RO","default_tier":"S T2","review_floor":"S T3"},{"id":"general","description":"General-purpose bounded worker for tasks that fit no specialist role.","capabilities":["workflow.selection","delegation.bounded"],"skills":[],"mcps":[],"best_for":"Bounded work with no specialist owner; escalate rather than widen scope.","permission_profile":"RW","default_tier":"S T2"}]}
+{
+  "_attribution": "llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving",
+  "version": 1,
+  "permission_profiles": {
+    "RO": {
+      "description": "Read-only. Investigation, evidence collection, review, telemetry.",
+      "required_access": [
+        "read",
+        "grep",
+        "glob",
+        "bash_readonly"
+      ],
+      "rules": [
+        "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."
+      ]
+    },
+    "RW": {
+      "description": "Read-write within an assigned bounded shard.",
+      "required_access": [
+        "read",
+        "grep",
+        "glob",
+        "edit",
+        "write",
+        "bash"
+      ],
+      "rules": [
+        "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."
+      ]
+    },
+    "ORCHESTRATOR": {
+      "description": "Plans, dispatches, and integrates; owns the overall session state.",
+      "required_access": [
+        "read",
+        "grep",
+        "glob",
+        "edit",
+        "write",
+        "bash",
+        "agent_dispatch"
+      ],
+      "rules": [
+        "Never bypasses a mandatory capability without declaring the gap first.",
+        "Owns fan-out sizing, shard boundaries, and integration/merge order.",
+        "Runs final verification before reporting completion to the user."
+      ]
+    }
+  },
+  "roles": [
+    {
+      "id": "orchestrator",
+      "description": "Plans work, resolves capabilities, dispatches bounded shards, integrates results.",
+      "capabilities": [
+        "orchestration.bootstrap",
+        "memory.recall",
+        "memory.checkpoint",
+        "workflow.selection",
+        "delegation.bounded"
+      ],
+      "skills": [
+        "using-superpowers",
+        "brainstorming",
+        "dispatching-parallel-agents",
+        "subagent-driven-development"
+      ],
+      "mcps": [
+        "sequential-thinking",
+        "mempalace"
+      ],
+      "best_for": "Any nontrivial task needing more than one shard or a risk-floor review seat.",
+      "permission_profile": "ORCHESTRATOR",
+      "default_tier": "S T3"
+    },
+    {
+      "id": "production-telemetry-collector",
+      "description": "Collects production logs/metrics/traces before an incident hypothesis is formed.",
+      "capabilities": [
+        "incident.telemetry_first"
+      ],
+      "skills": [
+        "incident-orchestration",
+        "incident-evidence"
+      ],
+      "mcps": [],
+      "best_for": "Incident evidence gathering; never forms a fix on its own.",
+      "permission_profile": "RO",
+      "default_tier": "W T0-T1"
+    },
+    {
+      "id": "route-data-flow-tracer",
+      "description": "Traces a request/data path across layers (frontend, API, DB, provider) read-only.",
+      "capabilities": [
+        "code.locate"
+      ],
+      "skills": [],
+      "mcps": [
+        "serena"
+      ],
+      "best_for": "Symptoms that cross architectural layers.",
+      "permission_profile": "RO",
+      "default_tier": "W T0-T1"
+    },
+    {
+      "id": "explore",
+      "description": "Read-only breadth search across a codebase: where something is defined, what calls it, which files are involved.",
+      "capabilities": [
+        "code.locate",
+        "tool.discovery"
+      ],
+      "skills": [],
+      "mcps": [],
+      "best_for": "Broad read-only location work before a decision; never edits.",
+      "permission_profile": "RO",
+      "default_tier": "W T0-T1"
+    },
+    {
+      "id": "db-concurrency-specialist",
+      "description": "Reviews transactional/locking correctness and concurrency-sensitive schema/code.",
+      "capabilities": [
+        "concurrency.review",
+        "database.schema_provenance"
+      ],
+      "skills": [],
+      "mcps": [
+        "db-client"
+      ],
+      "best_for": "Race conditions, stale claims, lock ordering, transactional boundaries.",
+      "permission_profile": "RO",
+      "default_tier": "X T3",
+      "review_floor": "X T4"
+    },
+    {
+      "id": "frontend-specialist",
+      "description": "Implements frontend changes that touch shared state, realtime or a native bridge, respecting shipped-client compatibility.",
+      "capabilities": [
+        "ui.design_system",
+        "test.behavioral"
+      ],
+      "skills": [
+        "frontend-design",
+        "design-system"
+      ],
+      "mcps": [
+        "playwright"
+      ],
+      "best_for": "Complex frontend state, realtime surfaces and native-bridge implementation work.",
+      "permission_profile": "RW",
+      "default_tier": "S T3"
+    },
+    {
+      "id": "provider-webhook-specialist",
+      "description": "Implements and reviews payment/webhook provider integrations (Stripe, Apple, Google).",
+      "capabilities": [
+        "billing.provider_evidence",
+        "push.provider_evidence",
+        "review.independent"
+      ],
+      "skills": [
+        "stripe-best-practices"
+      ],
+      "mcps": [
+        "billing-provider-api",
+        "push-provider-api"
+      ],
+      "best_for": "Webhook signature/idempotency, provider state reconciliation, refund delivery.",
+      "permission_profile": "RW",
+      "default_tier": "X T2",
+      "review_floor": "X T4"
+    },
+    {
+      "id": "adversarial-skeptic",
+      "description": "Independently challenges a conclusion, diagnosis, or diff before it ships.",
+      "capabilities": [
+        "review.adversarial",
+        "review.independent"
+      ],
+      "skills": [],
+      "mcps": [],
+      "best_for": "Money, auth, migration, and frozen-build-shaped review seats.",
+      "permission_profile": "RO",
+      "default_tier": "S T3",
+      "review_floor": "X T4"
+    },
+    {
+      "id": "test-engineer",
+      "description": "Writes and maintains behavioral/regression tests.",
+      "capabilities": [
+        "test.behavioral",
+        "workflow.tdd"
+      ],
+      "skills": [
+        "test-driven-development"
+      ],
+      "mcps": [],
+      "best_for": "Coverage gaps, regression tests for bug fixes, refactor safety nets.",
+      "permission_profile": "RW",
+      "default_tier": "S T2"
+    },
+    {
+      "id": "db-migration-author",
+      "description": "Sole authority for authoring SQL schema migrations.",
+      "capabilities": [
+        "config.migration_author",
+        "database.migration_checks",
+        "database.schema_provenance"
+      ],
+      "skills": [],
+      "mcps": [
+        "db-client"
+      ],
+      "best_for": "Any new migration file; never hand-write one outside this role.",
+      "permission_profile": "RW",
+      "default_tier": "S T3",
+      "review_floor": "X T4"
+    },
+    {
+      "id": "backend-fixer",
+      "description": "Implements bounded backend changes: a bug fix behind a validated hypothesis, or a feature/config change behind a failing test.",
+      "capabilities": [
+        "workflow.debug",
+        "test.behavioral"
+      ],
+      "skills": [
+        "systematic-debugging",
+        "test-driven-development"
+      ],
+      "mcps": [],
+      "best_for": "Backend implementation shards — bug fixes with a validated hypothesis, and the build phase of a feature or config flow.",
+      "permission_profile": "RW",
+      "default_tier": "S T2"
+    },
+    {
+      "id": "frontend-fixer",
+      "description": "Implements bounded frontend changes: a bug fix behind a validated hypothesis, or a feature change behind a failing test.",
+      "capabilities": [
+        "workflow.debug",
+        "test.behavioral",
+        "ui.design_system"
+      ],
+      "skills": [
+        "systematic-debugging",
+        "test-driven-development"
+      ],
+      "mcps": [
+        "playwright"
+      ],
+      "best_for": "Frontend/UI implementation shards — bug fixes with a validated hypothesis, and the build phase of a feature flow.",
+      "permission_profile": "RW",
+      "default_tier": "S T2"
+    },
+    {
+      "id": "code-simplifier",
+      "description": "Simplifies and clarifies recently changed code without changing behavior.",
+      "capabilities": [
+        "refactor.preservation",
+        "code.semantic_edit"
+      ],
+      "skills": [],
+      "mcps": [
+        "serena"
+      ],
+      "best_for": "Post-implementation cleanup passes.",
+      "permission_profile": "RW",
+      "default_tier": "S T2"
+    },
+    {
+      "id": "code-reviewer",
+      "description": "Performs the review pass at the task's review risk floor.",
+      "capabilities": [
+        "review.independent",
+        "workflow.review"
+      ],
+      "skills": [
+        "requesting-code-review",
+        "receiving-code-review"
+      ],
+      "mcps": [],
+      "best_for": "The review seat on every review-gated task.",
+      "permission_profile": "RO",
+      "default_tier": "S T2",
+      "review_floor": "S T3"
+    },
+    {
+      "id": "general",
+      "description": "General-purpose bounded worker for tasks that fit no specialist role.",
+      "capabilities": [
+        "workflow.selection",
+        "delegation.bounded"
+      ],
+      "skills": [],
+      "mcps": [],
+      "best_for": "Bounded work with no specialist owner; escalate rather than widen scope.",
+      "permission_profile": "RW",
+      "default_tier": "S T2"
+    }
+  ],
+  "role_aliases": {
+    "planner": {
+      "roles": [
+        "orchestrator"
+      ],
+      "note": "Planning is the orchestrator itself; it is never a separate dispatched agent."
+    },
+    "investigation": {
+      "roles": [
+        "route-data-flow-tracer"
+      ],
+      "note": "The read-only locate/trace pass that opens a bug fix."
+    },
+    "builders": {
+      "roles": [
+        "backend-fixer",
+        "frontend-fixer"
+      ],
+      "note": "Whichever side of the stack the shard owns."
+    },
+    "worker roles": {
+      "roles": [
+        "backend-fixer",
+        "frontend-fixer",
+        "code-simplifier"
+      ],
+      "note": "Mechanical W-tier shards."
+    },
+    "collectors": {
+      "roles": [
+        "route-data-flow-tracer",
+        "production-telemetry-collector"
+      ],
+      "note": "Evidence gathering, fanned out; research collectors use explore."
+    },
+    "synthesizer": {
+      "roles": [
+        "orchestrator"
+      ],
+      "note": "Synthesis stays with the orchestrator, which holds the whole evidence set."
+    },
+    "verifier": {
+      "roles": [
+        "test-engineer"
+      ],
+      "note": "Validation and smoke phases."
+    },
+    "domain specialist": {
+      "roles": [
+        "db-concurrency-specialist",
+        "provider-webhook-specialist",
+        "frontend-specialist"
+      ],
+      "note": "Whichever specialist owns the money, concurrency or security surface in question."
+    },
+    "log specialist": {
+      "roles": [
+        "production-telemetry-collector"
+      ],
+      "note": "Log and telemetry evidence during an incident."
+    },
+    "db/runtime specialist": {
+      "roles": [
+        "db-concurrency-specialist",
+        "route-data-flow-tracer"
+      ],
+      "note": "Database and runtime-state evidence during an incident."
+    }
+  }
+}

package/schemas/agent-roles.schema.json

@@ -1 +1,131 @@
-{"_attribution":"llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving","$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://raw.githubusercontent.com/tbogdan/llm-orchestrator/main/schemas/agent-roles.schema.json","title":"Agent role roster and permission profiles","type":"object","required":["version","permission_profiles","roles"],"properties":{"version":{"type":"integer","minimum":1},"permission_profiles":{"type":"object","additionalProperties":{"type":"object","required":["description","required_access","rules"],"properties":{"description":{"type":"string"},"required_access":{"type":"array","items":{"type":"string"}},"rules":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}},"roles":{"type":"array","items":{"type":"object","required":["id","description","capabilities","skills","mcps","best_for","permission_profile","default_tier"],"properties":{"id":{"type":"string","minLength":1},"description":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"skills":{"type":"array","items":{"type":"string"}},"mcps":{"type":"array","items":{"type":"string"}},"best_for":{"type":"string"},"permission_profile":{"type":"string"},"default_tier":{"type":"string","pattern":"^[WSXF] T[0-5](-T[0-5])?$","description":"Tier and thinking level pair resolved by registries/routing-matrix.json."},"review_floor":{"type":"string","pattern":"^[WSXF] T[0-5](-T[0-5])?$","description":"Minimum review pair for this role domain, where policies/routing.md states one."}},"additionalProperties":false}}}}
+{
+  "_attribution": "llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/tbogdan/llm-orchestrator/main/schemas/agent-roles.schema.json",
+  "title": "Agent role roster and permission profiles",
+  "type": "object",
+  "required": [
+    "version",
+    "permission_profiles",
+    "roles"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "permission_profiles": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "description",
+          "required_access",
+          "rules"
+        ],
+        "properties": {
+          "description": {
+            "type": "string"
+          },
+          "required_access": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "rules": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "roles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "description",
+          "capabilities",
+          "skills",
+          "mcps",
+          "best_for",
+          "permission_profile",
+          "default_tier"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": {
+            "type": "string"
+          },
+          "capabilities": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "skills": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "mcps": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "best_for": {
+            "type": "string"
+          },
+          "permission_profile": {
+            "type": "string"
+          },
+          "default_tier": {
+            "type": "string",
+            "pattern": "^[WSXF] T[0-5](-T[0-5])?$",
+            "description": "Tier and thinking level pair resolved by registries/routing-matrix.json."
+          },
+          "review_floor": {
+            "type": "string",
+            "pattern": "^[WSXF] T[0-5](-T[0-5])?$",
+            "description": "Minimum review pair for this role domain, where policies/routing.md states one."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "role_aliases": {
+      "type": "object",
+      "description": "Generic function words used in workflow role tables, each resolving to one or more concrete role ids.",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "roles",
+          "note"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "roles": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            }
+          },
+          "note": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/workflows/config.md

@@ -29,7 +29,7 @@ Infrastructure API MCPs, harness config skill.
 
 | Phase | Roles | Pair |
 |---|---|---|
-| Plan | planner | S T2 |
+| Plan | orchestrator | S T2 |
 | Standard config change | backend-fixer | S T2 |
 | DB migration (migration + provenance) | db-migration-author | S T3 |
 | Migration on money tables | db-migration-author | S T3 implementation + **X T4 review** |

package/workflows/feature.md

@@ -28,7 +28,7 @@ no clarification is needed).
 
 | Phase | Roles | Pair |
 |---|---|---|
-| Plan / design | planner, code-architect | S T3; X T3–T4 complex; F T4 frontier |
+| Plan / design | orchestrator (plus `feature-dev-code-architect` where the harness has it) | S T3; X T3–T4 complex; F T4 frontier |
 | TDD | test-engineer | S T2 |
 | Standard implementation (API CRUD, UI components) | backend-fixer, frontend-fixer | S T2 |
 | Complex state / realtime / native bridge | frontend-specialist | S T3 |

package/workflows/refactor.md

@@ -19,13 +19,13 @@
 
 ## Available
 
-Bounded ≤2-file builder, code-explorer, traceability analysis where the project uses it.
+Bounded ≤2-file builder, the `explore` role, traceability analysis where the project uses it.
 
 ## Roles and routing by phase
 
 | Phase | Roles | Pair |
 |---|---|---|
-| Analysis + incremental plan | code-simplifier, code-explorer | S T2 |
+| Analysis + incremental plan | orchestrator, code-simplifier, explore | S T2 |
 | Coverage | test-engineer | S T2 |
 | Mechanical steps (moves, scoped extractions) | worker roles | W T0 |
 | Refactor in money or security areas | domain specialist | S T3 implementation + X T4 review |