agents-united 0.6.0 → 0.7.0

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,19 @@ 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`) |
+
+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).
+
 ---
 ## 🌐 One Library, Every Assistant
 
@@ -541,20 +554,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

@@ -374,7 +374,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 +393,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 +523,12 @@ ${bodyStr}
         fallbacks: ["adaptive-session", "single-orchestrator"]
       }
     };
+    if (bundle.planningLoop?.enabled) {
+      manifest.planningLoop = bundle.planningLoop;
+      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 +550,40 @@ ${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 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 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 +593,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 +628,11 @@ ${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
+        );
         const roleName = this.stripSubagentPrefix(agentFile.replace(/\.md$/i, ""));
         artifacts.push({
           kind: "role",