agents-united 0.7.0 → 0.7.1

package/README.md

@@ -426,7 +426,11 @@ Organization bundles can opt into a **delegation-first planning protocol**: the
 | `summaryWordCap` | 150 | Words per Scope-of-Work Statement |
 | `maxIterations` | 8 | Per-invocation iteration cap (`.cline/agents/*.yml`) |
 
-Currently enabled for `digital-agency` (`planningLoop.enabled` in `registry/bundles.json`); rollout to the remaining bundles is tracked in [`ROADMAP.md`](ROADMAP.md). See [ADR 0014](./docs/adr/0014-subagent-first-planning-loop.md) and [Plan 012](./plans/012-subagent-first-planning-loop.md).
+Enabled for `digital-agency`. See [ADR 0014](./docs/adr/0014-subagent-first-planning-loop.md) and [Plan 012](./plans/012-subagent-first-planning-loop.md).
+
+### Planner-Orchestrator Mode (ADR 0015)
+
+**Tier-1 Domain Bundles** operate in **Planner-Orchestrator Mode**: the orchestrator plans **solo** with the user — Socratic alignment via `/grill-me` / `/grill-with-docs`, direct skill consultation, no specialist spawns during planning. A **Planning Aid Boundary** allows provisional estimates during planning but defers concrete deliverables to the delegation map. Execution is then delegated to `subagent_*` tools via a solo-composed **Delegation Map**. This mode is the default for all 30 domain bundles (engineering, design, security, business, research, architecture, marketing); `digital-agency` and future Organization Bundles remain in Subagent-First Mode. See [ADR 0015](./docs/adr/0015-planner-orchestrator-mode-for-domain-bundles.md) and [Plan 013](./plans/013-planner-orchestrator-mode-for-domain-bundles.md).
 
 ---
 ## 🌐 One Library, Every Assistant

package/dist/cli.js

@@ -41,6 +41,7 @@ var RegistryResolver = class {
       throw new Error(`Registry bundles.json not found at ${manifestPath}`);
     }
     this.bundlesManifest = await fs.readJson(manifestPath);
+    this.validateBundles(this.bundlesManifest);
     return this.bundlesManifest;
   }
   async getBundle(bundleName) {
@@ -193,6 +194,35 @@ var RegistryResolver = class {
       workflows: matchedWorkflows
     };
   }
+  /**
+   * ADR 0015 — fail-fast validation of planningLoop configuration.
+   * @throws if any bundle violates planner-orchestrator invariants.
+   */
+  validateBundles(manifest) {
+    const validModes = ["subagent-first", "planner-orchestrator"];
+    for (const [name, bundle] of Object.entries(manifest.bundles)) {
+      const pl = bundle.planningLoop;
+      if (!pl || !pl.enabled) continue;
+      const mode = pl.mode ?? "subagent-first";
+      if (!validModes.includes(mode)) {
+        throw new Error(
+          `Registry validation error: bundle "${name}" has unknown planningLoop.mode "${mode}". Valid modes: ${validModes.join(", ")}`
+        );
+      }
+      if (mode === "planner-orchestrator") {
+        if (pl.budget) {
+          throw new Error(
+            `Registry validation error: bundle "${name}" has planningLoop.mode "planner-orchestrator" but also declares a Consultation Budget (budget). Planner-orchestrator bundles must not declare budget.`
+          );
+        }
+        if (pl.sidekicks) {
+          throw new Error(
+            `Registry validation error: bundle "${name}" has planningLoop.mode "planner-orchestrator" but also declares sidekicks. Planner-orchestrator bundles must not declare sidekicks.`
+          );
+        }
+      }
+    }
+  }
 };
 
 // src/core/installer.ts
@@ -524,7 +554,14 @@ ${bodyStr}
       }
     };
     if (bundle.planningLoop?.enabled) {
-      manifest.planningLoop = bundle.planningLoop;
+      const mode = bundle.planningLoop.mode ?? "subagent-first";
+      manifest.planningLoop = {
+        enabled: true,
+        mode,
+        // Only emit budget/sidekicks for subagent-first bundles
+        ...mode === "subagent-first" && bundle.planningLoop.budget ? { budget: bundle.planningLoop.budget } : {},
+        ...mode === "subagent-first" && bundle.planningLoop.sidekicks ? { sidekicks: bundle.planningLoop.sidekicks } : {}
+      };
       if (bundle.personaAliases && Object.keys(bundle.personaAliases).length > 0) {
         manifest.personas = Object.entries(bundle.personaAliases).map(([persona, role]) => ({ persona, role }));
       }
@@ -551,30 +588,10 @@ ${bodyStr}
 ### Recommended Addon Policy
 When user tasks require capabilities from: ${addons.join(", ")}, explain the capability and request user confirmation to install via \`agents add <addon> -t cline -y\` before running the installation.` : "";
     const planning = bundle.planningLoop?.enabled === true ? bundle.planningLoop : void 0;
+    const mode = planning?.mode ?? "subagent-first";
     const budget = planning?.budget;
-    const delegationStep = planning ? "2. **Subagent-First Delegation Policy (ADR 0014)**: execute specialist work through the configured `subagent_*` agent tools (projected under `.cline/agents/`), assigning non-overlapping scopes. Complete specialist work in the main session ONLY if the subagent tools are genuinely absent from this runtime or the task is trivial (single-file read, one-line answer, formatting) \u2014 never as a convenience or speed choice." : "2. Delegate specialist tasks using the configured `subagent_*` agent tools (projected under `.cline/agents/`) when available, assigning non-overlapping scopes; fall back to Agent Teams (`team_spawn_teammate`) or session subagents as needed.";
-    const planningSection = planning ? `
-
-## Subagent-First Planning Dialogue Loop (ADR 0014)
-Run this loop BEFORE any substantive execution on a non-trivial task. Delegation-first is mandatory, not advisory.
-
-### Phase 0 \u2014 User Alignment
-If the user's brief is ambiguous, grill it Socratically with the user first: \`/grill-me\` (strategy / non-code) or \`/grill-with-docs\` (code & docs; writes ADRs and updates CONTEXT.md).
-
-### Phase 0.5 \u2014 Sidekick Clarification
-Spawn at most ${planning.sidekicks?.max ?? 2} relevant specialists (spawnable \`subagent_*\` tools) INTO this planning conversation to resolve remaining ambiguity. Sidekicks advise you; you relay their questions to the user.
-
-### Phase 1 \u2014 Specialist Council
-Have every relevant specialist return a Scope-of-Work Statement (max ${budget?.summaryWordCap ?? 150} words): (1) my scope, (2) inputs I need from peers, (3) my deliverable per my own workflows, (4) at most 2 open questions.
-
-### Phase 2 \u2014 Delegation Map
-Synthesize the council output into a task \u2192 specialist map and present it to the user BEFORE execution. Then delegate per the map.
-
-### Consultation Budget (hard caps)
-- Planning rounds (orchestrator \u2194 council): max ${budget?.maxPlanningRounds ?? 2}
-- Peer exchanges per specialist pair: max ${budget?.maxPeerExchangesPerPair ?? 2} directed questions
-- Scope-of-Work statement length: max ${budget?.summaryWordCap ?? 150} words
-- Specialist per-invocation iteration cap: maxIterations: ${budget?.maxIterations ?? 8} (rendered into .cline/agents/*.yml)` : "";
+    const delegationStep = planning ? mode === "subagent-first" ? "2. **Subagent-First Delegation Policy (ADR 0014)**: execute specialist work through the configured `subagent_*` agent tools (projected under `.cline/agents/`), assigning non-overlapping scopes. Complete specialist work in the main session ONLY if the subagent tools are genuinely absent from this runtime or the task is trivial (single-file read, one-line answer, formatting) \u2014 never as a convenience or speed choice." : "2. **Planner-Orchestrator Delegation Policy (ADR 0015)**: execute specialist work through the configured `subagent_*` agent tools (projected under `.cline/agents/`), assigning non-overlapping scopes. Complete specialist work in the main session ONLY if the subagent tools are genuinely absent from this runtime or the task is trivial (single-file read, one-line answer, formatting) \u2014 never as a convenience or speed choice." : "2. Delegate specialist tasks using the configured `subagent_*` agent tools (projected under `.cline/agents/`) when available, assigning non-overlapping scopes; fall back to Agent Teams (`team_spawn_teammate`) or session subagents as needed.";
+    const planningSection = planning ? mode === "subagent-first" ? "\n\n## Subagent-First Planning Dialogue Loop (ADR 0014)Run this loop BEFORE any substantive execution on a non-trivial task. Delegation-first is mandatory, not advisory.\n\n### Phase 0 \u2014 User Alignment\nIf the user's brief is ambiguous, grill it Socratically with the user first: `/grill-me` (strategy / non-code) or `/grill-with-docs` (code & docs; writes ADRs and updates CONTEXT.md).\n\n### Phase 0.5 \u2014 Sidekick Clarification\nSpawn at most " + (planning.sidekicks?.max ?? 2) + " relevant specialists (spawnable `subagent_*` tools) INTO this planning conversation to resolve remaining ambiguity. Sidekicks advise you; you relay their questions to the user.\n\n### Phase 1 \u2014 Specialist Council\nHave every relevant specialist return a Scope-of-Work Statement (max " + (budget?.summaryWordCap ?? 150) + " words): (1) my scope, (2) inputs I need from peers, (3) my deliverable per my own workflows, (4) at most 2 open questions.\n\n### Phase 2 \u2014 Delegation Map\nSynthesize the council output into a task \u2192 specialist map and present it to the user BEFORE execution. Then delegate per the map.\n\n### Consultation Budget (hard caps)\n- Planning rounds (orchestrator \u2194 council): max " + (budget?.maxPlanningRounds ?? 2) + "\n- Peer exchanges per specialist pair: max " + (budget?.maxPeerExchangesPerPair ?? 2) + " directed questions\n- Scope-of-Work statement length: max " + (budget?.summaryWordCap ?? 150) + " words\n- Specialist per-invocation iteration cap: maxIterations: " + (budget?.maxIterations ?? 8) + " (rendered into .cline/agents/*.yml)" : "\n\n## Planner-Orchestrator Policy (ADR 0015)Plan solo, delegate execution. This mode replaces the Subagent-First Planning Dialogue Loop for single-discipline domain bundles.\n\n### Phase 0 \u2014 User Alignment (solo)\nIf the user's brief is ambiguous, grill it Socratically yourself: `/grill-me` (strategy / non-code) or `/grill-with-docs` (code & docs). Consult the bundle's skills directly whenever they help you plan \u2014 you have the same skill access as your specialists. Do NOT spawn specialists during planning.\n\n### Planning Aid Boundary\nWhile planning you may consult skills and reason to give the user PROVISIONAL answers and estimates. A concrete deliverable \u2014 data analysis, code, assets, documents \u2014 is specialist work: defer it to the delegation map, never produce it yourself during planning.\n\n### Phase 2 \u2014 Delegation Map (solo-composed)\nCompose the task \u2192 specialist map from your own domain expertise and the skill runbooks, and present it to the user BEFORE execution.\n\n### Execution\nDelegate every deliverable to the configured `subagent_*` agent tools (projected under `.cline/agents/`), assigning non-overlapping scopes. Complete specialist work in the main session ONLY if the subagent tools are genuinely absent from this runtime or the task is trivial (single-file read, one-line answer, formatting) \u2014 never as a convenience or speed choice." : "";
     const personaSection = planning && bundle.personaAliases && Object.keys(bundle.personaAliases).length > 0 ? `
 
 ### Persona \u2192 Spawnable Tool Map
@@ -632,6 +649,7 @@ ${addonSection}
           content,
           canonicalRel,
           bundle.planningLoop?.enabled === true ? bundle.planningLoop.budget?.maxIterations : void 0
+          // ADR 0015: planner-orchestrator has no budget → undefined → key absent from .yml
         );
         const roleName = this.stripSubagentPrefix(agentFile.replace(/\.md$/i, ""));
         artifacts.push({