agents-united 0.6.0 → 0.7.1

package/README.md

@@ -119,7 +119,7 @@ Agents United provides **24 curated bundles**, **46 specialized agents** (8 Orch
 | **🔒 Security Operations** | `security-operations` | — | `orchestrator-security` |
 | **🔬 Deep Technical Research** | `deep-research` | — | `orchestrator-research` |
 | **💼 Business Strategy & Economics** | `business-strategy` | — | `orchestrator-business` |
-| **🏢 Organization Bundles (Experimental)** | `digital-agency` 🚧 | *(Currently under development)* | `orchestrator-digital-agency-director` |
+| **🏢 Organization Bundles (Experimental)** | `digital-agency` ⚡ | *(Cross-functional composite)* | `orchestrator-marketing` (Campaign Director / Chris) |
 
 <details>
 <summary><strong>🔍 Click to expand full Department & Agent Roster Breakdown</strong></summary>
@@ -173,7 +173,7 @@ Agents United provides **24 curated bundles**, **46 specialized agents** (8 Orch
 - **Essentials Base (`business-strategy`)**: `subagent-business-panel-experts`
 
 #### 🏢 Organization Bundles (Tier 2 / Experimental)
-- **Digital Product Agency (`digital-agency` 🚧)**: *(Currently under development)*
+- **Digital Product Agency (`digital-agency` ⚡)**: 10-agent cross-functional AstrolabsAI team (Chris / Ava / Kaan / Jamileh / Yavuz / Jale + engineering, QA & compliance) with Tri-Tier MCP execution modes and the Subagent-First Planning Dialogue Loop (ADR 0014).
 
 </details>
 
@@ -415,6 +415,23 @@ Organization bundles operate across three dynamic execution envelopes:
 > [!TIP]
 > **Zero Friction Onboarding**: You can start working with your Lead Orchestrator immediately using native tools. If your task needs live integrations (e.g. *"Set up Playwright browser testing"*), your Orchestrator will inspect your OS, configure the exact MCP server, test the connection, and activate it interactively!
 
+### Subagent-First Planning Dialogue Loop (ADR 0014)
+
+Organization bundles can opt into a **delegation-first planning protocol**: the Lead Orchestrator plans *with the user* (Socratic grilling via `/grill-me` / `/grill-with-docs`) and *with the team* — spawning up to 2 **Planning Sidekicks** into the planning conversation, running a bounded **Specialist Council** (every relevant specialist returns a ≤150-word Scope-of-Work Statement), and presenting a **Delegation Map** before any execution starts. Inter-specialist discussion is bounded by a declarative **Consultation Budget**, and each specialist's per-invocation run is hard-capped via Cline `maxIterations`:
+
+| Budget cap | Default | Meaning |
+| :--- | :--- | :--- |
+| `maxPlanningRounds` | 2 | Orchestrator ↔ council cycles per task |
+| `maxPeerExchangesPerPair` | 2 | Directed questions per specialist pair |
+| `summaryWordCap` | 150 | Words per Scope-of-Work Statement |
+| `maxIterations` | 8 | Per-invocation iteration cap (`.cline/agents/*.yml`) |
+
+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
 
@@ -541,20 +558,25 @@ When contributing new skills or adapting external skills:
 3. **Deterministic Verifications**: Include clear validation commands, error recovery procedures, and code exemplars.
 
 ### 6. Pull Request (PR) Workflow
-1. **Create a Feature Branch**: Always branch from `dev`:
+
+We use a two-line branch model — `main` is the release line, `dev` is the **protected** integration line. Full walkthrough: [`docs/workflow-guide.md`](docs/workflow-guide.md).
+
+1. **Branch from a fresh `dev`** (direct pushes to `dev` are rejected — changes arrive via PR only):
    ```bash
-   git checkout dev
-   git pull origin dev
-   git checkout -b feat/your-feature-name
+   git switch dev && git pull origin dev
+   git switch -c feat/your-feature-name   # or fix/, docs/, ci/
    ```
 2. **Follow TDD (Red-Green-Refactor)**: Author failing unit/E2E tests in `tests/` before implementing code.
 3. **Run Pre-PR Verification**:
    ```bash
+   npm run typecheck && npm test
    npm run build
-   npm test
    git diff --cached   # Audit staged files for accidental secrets or temp files
    ```
-4. **Submit Pull Request**: Open a PR targeting the `dev` branch with a concise description of changes and test results.
+4. **Push early & open PR #1 → base `dev`**: CI runs automatically (typecheck, build, full Vitest suite on `ubuntu-latest`). The PR can only merge once the required **`test`** status check passes.
+5. **Release via PR #2 → base `main`** (compare `dev`): merging triggers **semantic-release** — `feat:` bumps the minor version, `fix:` the patch — then the sync workflow auto-merges `main` back into `dev`.
+
+> Commit messages follow **Conventional Commits**: `feat:` / `fix:` drive releases; `docs:`, `ci:`, `chore:`, `refactor:`, `test:`, `perf:` accumulate without releasing. Emergency production hotfixes branch from `main` and PR directly into it.
 
 ---
 

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
@@ -374,7 +404,7 @@ complete the role in the main session.`;
    * canonical agent markdown content. Cline 3.x consumes YAML files with
    * frontmatter (name, description) and treats the body as the agent system prompt.
    */
-  static renderConfiguredAgent(canonicalContent, canonicalRelPath) {
+  static renderConfiguredAgent(canonicalContent, canonicalRelPath, defaultMaxIterations) {
     const match = canonicalContent.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
     if (!match) {
       throw new Error(`Canonical agent ${canonicalRelPath} is missing YAML frontmatter.`);
@@ -393,6 +423,11 @@ complete the role in the main session.`;
     if (typeof parsed.description === "string" && parsed.description.trim().length > 0) {
       cleanFrontmatter.description = parsed.description.trim();
     }
+    if (typeof parsed.maxIterations === "number") {
+      cleanFrontmatter.maxIterations = parsed.maxIterations;
+    } else if (typeof defaultMaxIterations === "number") {
+      cleanFrontmatter.maxIterations = defaultMaxIterations;
+    }
     const frontmatterStr = yaml.stringify(cleanFrontmatter).trim();
     const bodyStr = match[2].trim();
     return `---
@@ -518,6 +553,19 @@ ${bodyStr}
         fallbacks: ["adaptive-session", "single-orchestrator"]
       }
     };
+    if (bundle.planningLoop?.enabled) {
+      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 }));
+      }
+    }
     return yaml.stringify(manifest);
   }
   /**
@@ -539,6 +587,20 @@ ${bodyStr}
     const addonSection = addons.length > 0 ? `
 ### 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 ? 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
+| Persona | Role / Spawnable tool |
+|---|---|
+${Object.entries(bundle.personaAliases).map(([persona, role]) => {
+      const target = role.startsWith("subagent-") ? `${role} \u2192 \`subagent_${this.stripSubagentPrefix(role).replace(/-/g, "_")}\`` : `${role} (you, the coordinator)`;
+      return `| ${persona} | ${target} |`;
+    }).join("\n")}` : "";
     return `# Agents United \u2014 ${bundle.name} Coordinator Rule
 ${marker}
 
@@ -548,9 +610,10 @@ ${marker}
 
 ## Activation Protocol
 1. At session start, read the Team Manifest (\`${manifestRelPath}\`) and coordinator role prompt (\`.agents/${coordinatorCanonical}\`).
-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.
+${delegationStep}
 3. For lightweight read-only research, use session subagents.
 4. Only specialist roles declared in the Team Manifest are active in this workspace.
+${planningSection}${personaSection}
 ${specialistLines.length > 0 ? `
 ### Installed Specialist Roles
 ${specialistLines.join("\n")}` : ""}
@@ -582,7 +645,12 @@ ${addonSection}
       const srcPath = path4.join(registryDir, "agents", agentFile);
       if (await fs2.pathExists(srcPath)) {
         const content = await fs2.readFile(srcPath, "utf8");
-        const rendered = this.renderConfiguredAgent(content, canonicalRel);
+        const rendered = this.renderConfiguredAgent(
+          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({
           kind: "role",