llm-orchestrator 1.3.0 → 1.4.0

package/commands/task.md

@@ -0,0 +1,62 @@
+---
+description: "Handle a task through the portable orchestration entrypoint"
+---
+<!-- llm-orchestrator · created by Bogdan-Gabriel Torcescu · https://www.linkedin.com/in/bogdantorcescu/ · keep this credit when copying or deriving -->
+
+Load and follow the `orchestrate-core` skill (or, in a project install, the bridge `.agents/skills/orchestrate/SKILL.md`) before handling this request.
+Mode: execute
+Arguments: $ARGUMENTS
+
+Execute the requested task within the project contract.
+
+Mandatory — before any planning or execution step, declare the status of each
+core tool in this order (present / gap declared / explicit user refusal):
+
+1. `using-superpowers` (orchestration.bootstrap — invoke first, always)
+2. `mempalace` recall (memory.recall)
+3. `mempalace` checkpoint (memory.checkpoint)
+4. `sequentialthinking` MCP (reasoning.checkpoints)
+5. `caveman` (communication.concise)
+6. `rtk` preflight `command -v rtk && rtk --version` (shell.rtk)
+7. `context7` before code/fix/update/review checks (docs.current)
+8. `exa` for any external or current fact (research.retrieve)
+9. `verification-before-completion` (verification.checks)
+
+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
+point. Never free text at the end of a message; no answer means `blocked_pending_user`, never
+implied approval. Subagents never ask the user: they return `question_for_user` in the handoff.
+
+A mandatory gap is declared first and a one-time install is recommended before
+continuing. Only after an explicit user refusal may work continue, and only in
+declared degraded mode (`degraded:` line in every plan, handoff and report) — never silently.
+
+Orchestrator: discover tools/permissions (installed / loaded / callable / denied); read the
+project's `## Orchestration bindings (project)` section; allocate task_id; record task/flow
+drawers; emit the pre-evaluation JSON; split the plan into small PlanShards before dispatch
+(one concern, one role, one R/W boundary, one measurable output); dispatch independent shards
+in parallel (2+ agents for MODERATE, 3+ COMPLEX, 4+ CRITICAL when independent work exists;
+parallel groups 2–6, max 8 active shards before synthesis); keep each shard at 8–15 iterations
+and requeue the unfinished remainder at 70%; pass compact drawer refs, scope, owner,
+dependencies, acceptance checks and output drawer — never transcripts; require the
+non-mutating RTK access preflight before each shard; route EVERY shard separately at dispatch
+time against the live inventory, filling its `routing` block (`pair`, `tier`,
+`thinking_level`, `model_requested`, `effort_requested`, `model_effective`,
+`effort_effective`, `review_floor`, `independent_review`, `selection_reason`,
+`inventory_revision`, `price_source`, `est_usd_per_task`) from the W/S/X/F tier and T0–T5
+thinking level in the routing policy, with risk floors and an independent reviewer seat that is
+never cut — never one pair for the whole task, never a silent downgrade below a tier floor
+(`blocked: no eligible model` instead), and on an inventory change re-route the remaining shards
+only; enforce G0–G6; checkpoint to memory every 6–8 tool calls or before
+compaction. If a child returns `Streaming response failed` with a resumable id, record
+`subagent_stream_recovery_pending`, resume that exact child with its original phase contract
+(max three attempts), else one fresh child only from a complete handoff, else
+`subagent_resume_unavailable`. On a required access deny, record
+`permission_recovery:{task_id}:{phase}:{role}`, stop the blocked session and launch one fresh
+session with the matching declared profile (RO/RW); a repeated deny is terminal
+`permission_blocked` — only a human can approve a non-restricted session. Never bypass a
+deny, weaken access grants or skip verification. Integrate only after diff/test evidence; record
+`used_mcps` and verification; run the post-integration cleanup gate before claiming done.
+Sequentialthinking schema: `revisesThought` and `branchFromThought` are integers >= 1
+(use 1 as sentinel when false), never 0/null/omitted.

package/lib/adapter-renderer.mjs

@@ -28,7 +28,11 @@ Ask the user only through this harness's native question mechanism, batched into
 Use the \`orchestrate\` skill with the intent \`task\`, \`plan\`, \`status\`, \`cancel\`, or \`verify\` when the harness does not provide a matching native command.
 `;
 
+// OpenCode and Kilo load agent files from both `agent/` and `agents/`; the singular form is kept.
 const AGENT_DIRECTORIES = {claude: '.claude/agents', opencode: '.opencode/agent', kilo: '.kilo/agent'};
+// Frontmatter format per harness; Codex has no native agent-file format, so its
+// generic `.agents/agents` copy uses the Claude format the plugin also ships.
+const AGENT_FORMATS = {claude: 'claude', opencode: 'opencode', kilo: 'kilo', codex: 'claude'};
 
 /** Where each harness keeps the flow-adherence hooks: merged JSON, or a plugin file of our own. */
 export const FLOW_HOOK_TARGETS = {
@@ -112,7 +116,7 @@ export function renderAdapter({harness, capabilities = [], installMode = 'extern
 
   if (withAgents) {
     const agentDirectory = AGENT_DIRECTORIES[harness] ?? '.agents/agents';
-    for (const agent of agentFiles(agentDirectory)) {
+    for (const agent of agentFiles(agentDirectory, AGENT_FORMATS[harness])) {
       const native = generatedFile({...agent, kind: 'agent-file', existingFiles, ownedPaths: owned});
       if (native.action === 'conflict') conflicts.push(native.path);
       else files.push(native);

package/lib/router.mjs

@@ -209,10 +209,14 @@ function effortScale(model) {
   return model.thinking?.control === 'budget_tokens' ? BUDGET_ORDER : EFFORT_ORDER;
 }
 
-function desiredEffort(model, level) {
+function desiredEffort(model, level, tier = null) {
   const matrix = loadMatrix();
   const row = matrix.thinking_levels[level];
   if (!row) return null;
+  // A model seated on a tier below its home runs a declared, lower effort there so it
+  // is score-matched to that tier's model rather than over-provisioned.
+  const override = tier ? model.thinking?.tier_effort?.[tier]?.[level] : undefined;
+  if (override) return override;
   if (model.thinking?.control === 'budget_tokens') {
     if (['T0', 'T1'].includes(level)) return 'disabled';
     if (['T2', 'T3'].includes(level)) return 'enabled';
@@ -228,8 +232,8 @@ function desiredEffort(model, level) {
  * about the evidence, not licence to invent an enum: we take the model's cheapest
  * published setting that is at least as deep as the request, or nothing.
  */
-function resolveEffort(model, level) {
-  const desired = desiredEffort(model, level);
+function resolveEffort(model, level, tier = null) {
+  const desired = desiredEffort(model, level, tier);
   if (desired === null) return { effort: null, substituted: false };
   const levels = Array.isArray(model.thinking?.levels) ? model.thinking.levels : [];
   if (levels.length === 0 || levels.includes(desired)) return { effort: desired, substituted: false };
@@ -341,10 +345,10 @@ export function rankModels({
     if (model.caps?.requires_explicit_flag && !explicitFable51) continue;
     if (model.caps?.requires_explicit_flag) cap_notes.push(`capped exception: ≤${Math.round((model.caps.share_max ?? 0) * 100)}% of dispatches, explicit request only`);
 
-    const resolved = resolveEffort(model, parsed.level);
+    const resolved = resolveEffort(model, parsed.level, parsed.tier);
     let effort = resolved.effort;
     if (effort === null) continue; // no expression for this thinking level on this control
-    if (resolved.substituted) cap_notes.push(`no measured \`${desiredEffort(model, parsed.level)}\` point; nearest published setting is \`${effort}\``);
+    if (resolved.substituted) cap_notes.push(`no measured \`${desiredEffort(model, parsed.level, parsed.tier)}\` point; nearest published setting is \`${effort}\``);
 
     const scale = effortScale(model);
     const cap = model.caps?.max_effort ?? scale[scale.length - 1];

package/models/top-models.json

@@ -366,6 +366,7 @@
       "admission": "incumbent",
       "tier": "X",
       "eligible_tiers": [
+        "S",
         "X"
       ],
       "supersedes": "gpt-5-6-sol",
@@ -388,7 +389,10 @@
         ],
         "always_on": false,
         "default_for_tier": "high",
-        "note": "Same Codex policy as GPT-5.6 Sol: ceiling `high`; T4 is `high` plus an independent second Sol `high` reviewer with no shared history. The API also accepts `none`, which is not measured and never routed."
+        "note": "Same Codex policy as GPT-5.6 Sol: ceiling `high`; T4 is `high` plus an independent second Sol `high` reviewer with no shared history. The API also accepts `none`, which is not measured and never routed. On the S seat it runs one notch down (tier_effort), score-matched to Terra.",
+        "tier_effort": {
+          "S": {"T1": "low", "T2": "low", "T3": "medium"}
+        }
       },
       "price": {
         "input_usd_per_mtok": 2,
@@ -463,7 +467,7 @@
       },
       "notes": [
         "Successor to GPT-5.6 Sol on the Codex X seat at half the per-token price ($2/$10 vs $4/$20, permanent pricing). It is cheaper per completed task at every measured effort and scores equal or higher at each (high 43 @ $0.37 vs 42 @ $0.81); GPT-5.6 Sol stays routable as its fallback.",
-        "Its `medium` (40 @ $0.25) also dominates GPT-5.6 Terra `xhigh` (38 @ $0.63); the S seat stays Terra because an incumbent's tier is its ladder seat, not a score — see the routing note."
+        "Also holds the Codex S seat: at every S pair it is cheaper and stronger than GPT-5.6 Terra (S T2: `low` 34 @ $0.13 vs Terra `medium` 30 @ $0.18; S T3: `medium` 40 @ $0.25 vs Terra `high` 34 @ $0.34). Terra stays routable as the S fallback."
       ],
       "sources": [
         "https://artificialanalysis.ai/models/gpt-6-sol",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-orchestrator",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "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": {
@@ -49,6 +49,7 @@
     "skills",
     "hooks",
     "agents",
+    "commands",
     ".claude-plugin"
   ],
   "scripts": {

package/policies/routing.md

@@ -75,7 +75,7 @@ the incumbents below are role mappings, not guarantees of availability.
 | Tier | Role | Claude incumbent | Codex incumbent |
 | --- | --- | --- | --- |
 | **W** worker | local, mechanical, repetitive, well-defined: code search, classification, extraction, small edits, boilerplate, simple tests, consistency checks, scoped transforms | Haiku 4.5 (`claude-haiku-4-5`) | `gpt-6-luna`, falling back to `gpt-5.6-luna` |
-| **S** standard | default software-engineering model: normal implementation, frontend/backend, moderate debugging, tests, reasonable multi-file refactors, codebase analysis, tool use | Sonnet 5 (`claude-sonnet-5`) | `gpt-5.6-terra` |
+| **S** standard | default software-engineering model: normal implementation, frontend/backend, moderate debugging, tests, reasonable multi-file refactors, codebase analysis, tool use | Sonnet 5 (`claude-sonnet-5`) | `gpt-6-sol` one notch down, falling back to `gpt-5.6-terra` |
 | **X** senior | hard debugging, architecture, concurrency, migrations, security, auth, payments, billing, backwards compatibility, critical code review, many invariants | Opus 5.5 (`claude-opus-5-5`), falling back to Opus 5 (`claude-opus-5`) | `gpt-6-sol`, falling back to `gpt-5.6-sol` |
 | **F** frontier | exceptional escalation: very ambiguous, long-horizon, cross-system, major architecture, very large codebase, planning under heavy constraints, or when X fails to produce a solid solution | Fable 5 (`claude-fable-5`) — default F. Fable 5.1 (`claude-fable-5-1`) is a hard-capped exception: **≤2% of all dispatches**, explicit request or documented F-T4 failure on Fable 5 only | GPT-6 Astra (`gpt-6-astra`) — a real single-agent frontier tier, no decomposition workaround needed |
 
@@ -86,7 +86,7 @@ Verified prices (Sep 2026, provider pricing pages), USD in/out per MTok:
 | Tier | Claude model | Claude $ in/out | Codex model | Codex $ in/out |
 | --- | --- | --- | --- | --- |
 | W | Haiku 4.5 (200K ctx) | $1 / $5 | `gpt-6-luna` (1.05M ctx); fallback `gpt-5.6-luna` $0.20 / $1.20 | $0.10 / $0.50 |
-| S | Sonnet 5 (1M ctx) | $2 / $10 | `gpt-5.6-terra` (1.05M ctx) | $2 / $12 |
+| S | Sonnet 5 (1M ctx) | $2 / $10 | `gpt-6-sol` one effort notch down (T1/T2 `low`, T3 `medium`); fallback `gpt-5.6-terra` $2 / $12 | $2 / $10 |
 | X | Opus 5.5 (1M ctx); fallback Opus 5 $5 / $25 | $4 / $20 | `gpt-6-sol` (1.05M ctx); fallback `gpt-5.6-sol` $4 / $20 | $2 / $10 |
 | F | Fable 5 (1M ctx) | $10 / $50 | `gpt-6-astra` (1.05M ctx) | $10 / $50 list — **but the cheapest F per completed task of any model here** |
 | F+ (≤2%) | Fable 5.1 (1M ctx) | $10 / $50 list — **effective cost significantly higher** (always-on thinking, longer turns, more output tokens per task) | — (Astra covers F) | — |

package/protocol.md

@@ -46,7 +46,9 @@ flow, but only by declaring it: `llm-orchestrator run start --trivial "<reason>"
 declaration and its reason are recorded; an undeclared skip is recorded as a skipped flow. A bug
 fix that needs a regression test, or any change across two or more files, is **not** trivial — it
 is a typed run. A trivial run that grows past that line gets one reminder to reopen it as a typed
-run, and the audit counts it as `trivial_overreach`. A trivial run lasts one turn.
+run, and the audit counts it as `trivial_overreach`. A trivial run lasts one turn. Skipping the
+flow never lifts edit denial: under the orchestrator agent the trivial change is dispatched to
+`general`; without an orchestrator agent it is made by the harness's default build agent.
 
 ```json
 {