@sulhadin/orchestrator 3.0.0-beta.7 → 3.0.0-beta.9

package/bin/index.js

@@ -95,6 +95,123 @@ function rmDirRecursive(dir) {
   fs.rmdirSync(dir);
 }
 
+/**
+ * Simple YAML config merge: adds new keys from template, preserves user values.
+ * Works with flat and one-level nested YAML (no deep nesting needed for config.yml).
+ */
+function mergeConfigYaml(userContent, templateContent) {
+  const userLines = userContent.split("\n");
+  const templateLines = templateContent.split("\n");
+
+  // Parse YAML into { key: value } with awareness of sections
+  function parseYaml(lines) {
+    const result = {};
+    let currentSection = null;
+    for (const line of lines) {
+      // Skip comments and empty lines for parsing, but we'll preserve them
+      if (line.trim() === "" || line.trim().startsWith("#")) continue;
+      // Top-level section (no indent)
+      const sectionMatch = line.match(/^(\w[\w_-]*):\s*$/);
+      if (sectionMatch) {
+        currentSection = sectionMatch[1];
+        result[currentSection] = result[currentSection] || {};
+        continue;
+      }
+      // Nested key (2-space indent)
+      const nestedMatch = line.match(/^  (\w[\w_-]*):\s*(.+)?$/);
+      if (nestedMatch && currentSection) {
+        const key = nestedMatch[1];
+        const value = nestedMatch[2] || "";
+        if (!result[currentSection]) result[currentSection] = {};
+        // Check if this is a sub-section (value is empty, next lines are indented more)
+        if (!value) {
+          result[currentSection][key] = result[currentSection][key] || {};
+        } else {
+          result[currentSection][key] = value;
+        }
+        continue;
+      }
+      // Deeper nested key (4-space indent)
+      const deepMatch = line.match(/^    (\w[\w_-]*):\s*(.+)$/);
+      if (deepMatch && currentSection) {
+        // Find parent key (last nested key without value)
+        const parentKeys = Object.keys(result[currentSection] || {});
+        const parentKey = parentKeys.reverse().find(
+          (k) => typeof result[currentSection][k] === "object"
+        );
+        if (parentKey) {
+          result[currentSection][parentKey][deepMatch[1]] = deepMatch[2];
+        }
+      }
+    }
+    return result;
+  }
+
+  const userParsed = parseYaml(userLines);
+  const templateParsed = parseYaml(templateLines);
+
+  // Build merged config: start with template (has comments + structure), fill with user values
+  const merged = [];
+  let currentSection = null;
+  let currentSubSection = null;
+
+  for (const line of templateLines) {
+    const sectionMatch = line.match(/^(\w[\w_-]*):\s*$/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1];
+      currentSubSection = null;
+      merged.push(line);
+      continue;
+    }
+
+    const nestedMatch = line.match(/^  (\w[\w_-]*):\s*(.+)?$/);
+    if (nestedMatch && currentSection) {
+      const key = nestedMatch[1];
+      const templateValue = nestedMatch[2] || "";
+
+      if (!templateValue) {
+        // Sub-section header (e.g., "models:")
+        currentSubSection = key;
+        merged.push(line);
+        continue;
+      }
+
+      // Has a value → this is a flat key, reset sub-section
+      currentSubSection = null;
+
+      // Check if user has this key
+      const userSection = userParsed[currentSection];
+      if (userSection && userSection[key] !== undefined && typeof userSection[key] !== "object") {
+        merged.push(`  ${key}: ${userSection[key]}`);
+        continue;
+      }
+      // New key — use template value
+      merged.push(line);
+      continue;
+    }
+
+    const deepMatch = line.match(/^    (\w[\w_-]*):\s*(.+)$/);
+    if (deepMatch && currentSection && currentSubSection) {
+      const key = deepMatch[1];
+      const userSection = userParsed[currentSection];
+      if (userSection && typeof userSection[currentSubSection] === "object") {
+        const userValue = userSection[currentSubSection][key];
+        if (userValue !== undefined) {
+          merged.push(`    ${key}: ${userValue}`);
+          continue;
+        }
+      }
+      // New key — use template value
+      merged.push(line);
+      continue;
+    }
+
+    merged.push(line);
+  }
+
+  return merged.join("\n");
+}
+
 function extractOrchestraSection(content) {
   const startIdx = content.indexOf(ORCHESTRA_SECTION_START);
   if (startIdx === -1) return null;
@@ -302,11 +419,14 @@ function run() {
       console.log("  [+] Restored knowledge.md");
     }
 
-    // Restore config.yml (user's customizations take priority)
+    // Merge config.yml: new template keys added, user values preserved
     if (hasConfig && fs.existsSync(configBackup)) {
-      fs.copyFileSync(configBackup, path.join(orchestraDest, "config.yml"));
+      const userConfig = fs.readFileSync(configBackup, "utf-8");
+      const templateConfig = fs.readFileSync(path.join(orchestraDest, "config.yml"), "utf-8");
+      const mergedConfig = mergeConfigYaml(userConfig, templateConfig);
+      fs.writeFileSync(path.join(orchestraDest, "config.yml"), mergedConfig);
       fs.unlinkSync(configBackup);
-      console.log("  [+] Restored config.yml (user customizations preserved)");
+      console.log("  [+] Merged config.yml (user values preserved, new keys added)");
     }
   } else {
     // ── Fresh install ──

package/bin/merge-config.test.js

@@ -0,0 +1,135 @@
+const { describe, it } = require("node:test");
+const assert = require("node:assert");
+const fs = require("fs");
+const path = require("path");
+
+// Extract mergeConfigYaml from index.js
+const src = fs.readFileSync(path.join(__dirname, "index.js"), "utf-8");
+const match = src.match(/function mergeConfigYaml\([\s\S]*?^}/m);
+eval(match[0]);
+
+const userConfig = `pipeline:
+  models:
+    quick: haiku
+    standard: sonnet
+    complex: opus
+  rfc_approval: skip
+  push_approval: auto
+  review: required
+  parallel: disabled
+
+thresholds:
+  re_review_lines: 50
+  phase_time_limit: 20
+  phase_tool_limit: 40
+  stuck_retry_limit: 5
+
+verification:
+  typecheck: "yarn tsc --noEmit"
+  test: "yarn test"
+  lint: "yarn lint"
+`;
+
+const templateConfig = `# Orchestra Configuration
+# Customize pipeline behavior, thresholds, and verification commands.
+
+pipeline:
+  # Model selection per phase complexity
+  models:
+    trivial: haiku
+    quick: sonnet
+    standard: sonnet
+    complex: opus
+  rfc_approval: required
+  push_approval: required
+  review: required
+  parallel: disabled
+  default_pipeline: full
+  default_complexity: standard
+  max_rfc_rounds: 3
+
+thresholds:
+  milestone_lock_timeout: 120
+  re_review_lines: 30
+  phase_time_limit: 15
+  phase_tool_limit: 40
+  stuck_retry_limit: 3
+
+verification:
+  typecheck: "npx tsc --noEmit"
+  test: "npm test"
+  lint: "npm run lint"
+`;
+
+describe("mergeConfigYaml", () => {
+  const result = mergeConfigYaml(userConfig, templateConfig);
+
+  describe("new template keys are added", () => {
+    it("adds trivial model tier", () => {
+      assert.ok(result.includes("trivial: haiku"));
+    });
+
+    it("adds default_pipeline", () => {
+      assert.ok(result.includes("default_pipeline: full"));
+    });
+
+    it("adds default_complexity", () => {
+      assert.ok(result.includes("default_complexity: standard"));
+    });
+
+    it("adds max_rfc_rounds", () => {
+      assert.ok(result.includes("max_rfc_rounds: 3"));
+    });
+
+    it("adds milestone_lock_timeout", () => {
+      assert.ok(result.includes("milestone_lock_timeout: 120"));
+    });
+  });
+
+  describe("user values are preserved", () => {
+    it("keeps user models.quick value", () => {
+      assert.ok(result.includes("quick: haiku"));
+    });
+
+    it("keeps user rfc_approval", () => {
+      assert.ok(result.includes("rfc_approval: skip"));
+    });
+
+    it("keeps user push_approval", () => {
+      assert.ok(result.includes("push_approval: auto"));
+    });
+
+    it("keeps user re_review_lines", () => {
+      assert.ok(result.includes("re_review_lines: 50"));
+    });
+
+    it("keeps user phase_time_limit", () => {
+      assert.ok(result.includes("phase_time_limit: 20"));
+    });
+
+    it("keeps user stuck_retry_limit", () => {
+      assert.ok(result.includes("stuck_retry_limit: 5"));
+    });
+
+    it("keeps user verification commands", () => {
+      assert.ok(result.includes('typecheck: "yarn tsc --noEmit"'));
+      assert.ok(result.includes('test: "yarn test"'));
+      assert.ok(result.includes('lint: "yarn lint"'));
+    });
+  });
+
+  describe("template structure is preserved", () => {
+    it("keeps comments from template", () => {
+      assert.ok(result.includes("# Orchestra Configuration"));
+      assert.ok(result.includes("# Model selection per phase complexity"));
+    });
+
+    it("maintains section order", () => {
+      const pipelineIdx = result.indexOf("pipeline:");
+      const thresholdsIdx = result.indexOf("thresholds:");
+      const verificationIdx = result.indexOf("verification:");
+      assert.ok(pipelineIdx < thresholdsIdx);
+      assert.ok(thresholdsIdx < verificationIdx);
+    });
+  });
+});

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@sulhadin/orchestrator",
-  "version": "3.0.0-beta.7",
+  "version": "3.0.0-beta.9",
   "description": "AI Team Orchestration System — multi-role coordination for Claude Code",
   "bin": "bin/index.js",
   "scripts": {
+    "test": "node --test bin/**/*.test.js",
     "template": "node bin/build-template.js",
     "prepare": "husky"
   },
@@ -23,7 +24,8 @@
     "ai",
     "agent",
     "multi-agent",
-    "claude-code"
+    "claude-code",
+    "team"
   ],
   "repository": {
     "type": "git",

package/template/.claude/agents/conductor.md

@@ -26,7 +26,12 @@ When started:
    - Glob `.orchestra/milestones/*/milestone.md`
    - Read each to check Status field
    - `status: in-progress` → resume | `status: planning` → start | all `done` → report complete
-6. Begin execution loop.
+6. If milestone scope spans 3+ directories or 20+ files, launch scout sub-agent (haiku):
+   - Scan project structure within milestone's phase scopes
+   - Return max 30-line map: `path/file — one-line description`
+   - Write map to context.md under `## Codebase Map`
+   - For smaller scopes, skip — sub-agents can explore directly.
+7. Begin execution loop.
 
 ## Pipeline Selection
 
@@ -38,13 +43,13 @@ Read `Complexity` from milestone.md + `pipeline` from config.yml:
 | `standard` | Phases → Review → Push |
 | `full` | Architect → Phases → Review → Push |
 
-Default: `full` if Complexity missing.
+Default: config.yml `pipeline.default_pipeline` (default `full`).
 
 ## Milestone Lock
 
 Before starting a milestone:
 1. Check milestone.md for `Locked-By` field
-2. If locked and < 2 hours old → skip this milestone
+2. If locked and < config.yml `thresholds.milestone_lock_timeout` minutes → skip this milestone
 3. If no lock or stale → write `Locked-By: {timestamp}`
 4. On completion or failure → remove `Locked-By`
 
@@ -59,53 +64,103 @@ For each phase:
 - Read phase file — extract role, skills, scope, acceptance criteria, depends_on
 - Check phase status — skip if `done`, resume if `in-progress`
 - Verify dependencies — all `depends_on` phases must be `done`
+- Select model: read `complexity` from phase file (default: config.yml `pipeline.default_complexity`), map via `pipeline.models:`
 
-### 2. Delegate to Phase Sub-Agent
-Launch a sub-agent with this prompt template:
+### 2. Pre-read & Compose Prompt (Conductor does this)
+
+Before launching the sub-agent, conductor reads required files and inlines
+their content into the prompt. This eliminates sub-agent startup Read calls.
+Cache role/skills content in conductor context — don't re-read for consecutive
+phases with the same role.
+
+1. Read `.orchestra/roles/{role}.md` → role_content (skip if same role as previous phase)
+2. Read skill files from phase → skills_content (skip already-read skills)
+3. Read phase file → phase_content
+4. Extract verification commands from config.yml (read once at startup, reuse)
+5. Read codebase map from context.md (if exists) → codebase_map
+
+### 3. Delegate to Phase Sub-Agent
+
+Launch sub-agent with model from pre-flight step. Always use default
+(general-purpose) subagent_type — role identity is provided in the prompt,
+using named types like "backend-engineer" would load a conflicting agent definition.
+Save the sub-agent ID for potential fix cycles via SendMessage.
+
+Prompt structure: static content first (better prefix cache hit chance when
+same role runs consecutive phases), dynamic content last.
 
 ```
 You are executing a phase for Orchestra conductor.
-
-**Role:** Read `.orchestra/roles/{role}.md` — adopt this identity.
-**Skills:** Read these skill files: {skill_files_list}
-**Phase file:** Read `{phase_file_path}` for objective, scope, and acceptance criteria.
-**Config:** Read `.orchestra/config.yml` for verification commands.
 Rules from `.claude/rules/*.orchestra.md` are automatically loaded.
 
+**Verification commands (run in this order, stop at first failure):**
+typecheck: {typecheck_cmd}
+test: {test_cmd}
+lint: {lint_cmd}
+
+**Role:**
+{role_content}
+
+**Skills:**
+{skills_content}
+
+**Phase:**
+{phase_content}
+
+**Codebase map:**
+{codebase_map}
+
+**Previous phase summary:**
+{previous_phase_result_summary — concise summary of decisions and artifacts
+that affect this phase. Omit for first phase.}
+
 ## Your Task
-1. Research — read existing code in scope, check dependency versions
+1. Research — read existing code in scope (use codebase map to target files)
 2. Implement — write code + tests following role identity + skill checklists
-3. Verify — run verification commands from config.yml (typecheck → test → lint)
-   - If verification fails, fix and retry (max {stuck_retry_limit} attempts)
-   - If still failing after max retries, report failure with error summary
-4. Acceptance — verify each acceptance criterion from phase file is satisfied
-5. Commit — one conventional commit per phase
+3. Verify — run verification commands: typecheck → test → lint (in order, stop at first failure).
+   Fix and retry until all pass (max {stuck_retry_limit} attempts). Error logs stay in your
+   context — this is intentional, your context is ephemeral.
+4. Acceptance — check each acceptance criterion from phase. Note any gaps.
+5. Report — when all verification passes and acceptance is checked, report back.
+   Do NOT commit — conductor handles commit.
 
 ## Return Format
-Report back with:
 - status: done | failed
-- commit_hash: (if committed)
 - files_changed: [list]
 - verification_retries: N
-- error_summary: (if failed, max 5 lines)
+- error_summary: (if failed after max retries, include last error)
 - acceptance_notes: (any unverified criteria)
+- notes: (workarounds flagged, effort concerns, anything conductor should know)
 ```
 
-### 3. Process Sub-Agent Result (Conductor does this)
-- If **done**: update phase file status → `done`, fill Result section, update context.md
-- If **failed**: log in context.md, check stuck_retry_limit, decide to retry or escalate
+### 4. Process Sub-Agent Result (Conductor does this)
+
+- If **done** (verification passed):
+  1. Conductor commits → update phase status → `done`, update context.md
+  2. Store sub-agent ID for potential review fix cycle
+- If **failed** (verification failed after max retries):
+  1. Log in context.md: phase name, last error summary, retry count
+  2. Decide: retry with new sub-agent or escalate to user
+
+**Note:** Conductor owns commit only. Sub-agents own implementation + verification.
 
 ### Sub-Agent Configuration
-- Use worktree isolation when `pipeline.parallel: enabled`
-- Sub-agent inherits model from conductor config
+- Model selected per phase complexity via config.yml `pipeline.models:`
+- Use Agent tool `isolation: "worktree"` when `pipeline.parallel: enabled`
 - Each sub-agent starts with fresh context — no carryover from previous phases
+- Sub-agent runs its own verification loop (tight feedback, errors stay in ephemeral context)
+- Conductor stores sub-agent ID for potential review fix cycles
+- Conductor passes previous phase result summary to next phase
 
 ## Parallel Execution
 
 If config.yml `pipeline.parallel: enabled`:
 1. Read all phase files and `depends_on` fields
-2. Phases with `depends_on: []` launch as concurrent sub-agents with worktree isolation
-3. Merge results in phase order, verify after each merge
+2. Phases with `depends_on: []` launch as concurrent sub-agents:
+   - Use Agent tool with `run_in_background: true` and `isolation: "worktree"` for each
+   - Track launched count, process each completion notification as it arrives
+   - Proceed to step 3 only when all launched sub-agents have completed
+3. Merge results in phase order (sub-agents already verified in their worktrees)
 4. If `depends_on` not set on any phase → sequential (backward compatible)
 
 ## Review
@@ -116,7 +171,8 @@ After all implementation phases (unless config says `review: skip`):
 3. **approved** → push gate
 4. **approved-with-comments** → push gate, log comments in context.md
 5. **changes-requested** → fix cycle:
-   - Launch fix sub-agent with reviewer findings + relevant role
+   - Use SendMessage to continue the last phase's sub-agent with reviewer findings
+     (if sub-agent no longer available, launch new sub-agent with findings + role)
    - If fix < config `re_review_lines` → proceed
    - If fix >= config `re_review_lines` → abbreviated re-review
 
@@ -128,13 +184,13 @@ Read gate behavior from config.yml:
 
 ## Rejection Flow
 
-- **RFC Rejected:** Ask feedback → architect revises → re-submit (max 3 rounds).
+- **RFC Rejected:** Ask feedback → architect revises → re-submit (max config.yml `pipeline.max_rfc_rounds`).
 - **Push Rejected:** Ask feedback → create fix phase → re-submit.
 
 ## Milestone Completion
 
 After push:
-1. Update milestone.md `status: done`, remove `Locked-By`
+1. Update milestone.md `status: done`, remove `Locked-By`.
 2. Append 5-line retrospective to knowledge.md:
    ```
    ## Retro: {id} — {title} ({date})
@@ -161,14 +217,13 @@ On resume: read context.md, continue from last completed phase.
 
 When user types `/orchestra hotfix {description}`:
 1. Auto-create hotfix milestone + single phase
-2. Launch single sub-agent: implement → verify → commit
-3. Push immediately (no RFC, no review, no approval gates)
-4. Append one-liner to knowledge.md
-5. Return to normal execution if active
+2. Launch implementation sub-agent (model: standard) — implements, verifies, reports
+3. If done → conductor commits → push immediately (no RFC, no review, no gates)
+5. Append one-liner to knowledge.md
+6. Return to normal execution if active
 
 ## What Conductor Does NOT Do
 
-- Does NOT implement code (sub-agents do)
-- Does NOT run verification commands directly (sub-agents do)
+- Does NOT implement code (implementation sub-agents do)
 - Does NOT create milestones (PM does)
 - Does NOT modify Orchestra system files (Orchestrator does)

package/template/.claude/rules/acceptance-check.orchestra.md

@@ -1,13 +1,11 @@
 # Acceptance Check
 
-After verification gate passes (code compiles, tests pass, lint clean),
-check whether you built **the right thing** — not just whether it works.
+After implementation, check whether you built **the right thing** — not just whether it works.
 
 1. Re-read the phase file's acceptance criteria
-2. For EACH criterion, ask: "Does my implementation satisfy this?"
-3. If YES → proceed to commit
-4. If NO → fix it, re-run verification gate
-5. If UNCERTAIN → flag in context.md: "Unverified: {criterion} — {reason}"
+2. For EACH criterion: "Does my implementation satisfy this?"
+3. If YES → proceed
+4. If NO → fix it
+5. If UNCERTAIN → flag: "Unverified: {criterion} — {reason}"
 
 This catches "code works but doesn't do what was asked."
-Verification gate checks if code is correct. Acceptance check checks if code is complete.

package/template/.claude/rules/code-standards.orchestra.md

@@ -9,7 +9,7 @@
 **DRY** — Don't repeat yourself. Extract after second duplication, not before.
 
 **Zero-tolerance rules:**
-- No workarounds — if the right solution is hard, do it right. Flag effort in context.md.
+- No workarounds — if the right solution is hard, do it right. Flag effort in report or context.md.
 - No unused code — delete dead imports, functions, files. Don't comment out.
 - No breaking changes without migration — update every consumer.
 - Current library versions only — verify before using, don't assume from memory.

package/template/.orchestra/config.yml

@@ -2,6 +2,16 @@
 # Customize pipeline behavior, thresholds, and verification commands.
 
 pipeline:
+  # Model selection per phase complexity
+  # trivial: version bumps, env vars, config-only changes
+  # quick: single-file fixes, simple CRUD
+  # standard: typical features
+  # complex: new subsystems, architectural changes
+  models:
+    trivial: haiku
+    quick: sonnet
+    standard: sonnet
+    complex: opus
   # RFC approval gate: required | optional | skip
   rfc_approval: required
 
@@ -15,7 +25,19 @@ pipeline:
   # When enabled, phases with depends_on: [] run in parallel
   parallel: disabled
 
+  # Default pipeline when milestone Complexity is missing
+  default_pipeline: full  # quick | standard | full
+
+  # Default phase complexity when not set by PM
+  default_complexity: standard  # trivial | quick | standard | complex
+
+  # Max RFC rejection rounds before escalating to user
+  max_rfc_rounds: 3
+
 thresholds:
+  # Milestone lock timeout in minutes (stale locks are ignored)
+  milestone_lock_timeout: 120
+
   # Fix cycle: re-review if fix exceeds this many lines
   re_review_lines: 30
 

package/template/.orchestra/roles/product-manager.md

@@ -68,11 +68,12 @@ Cannot write: feature code, RFCs, architecture docs, review findings, system fil
 
 ```markdown
 ---
-role: backend-engineer | frontend-engineer | architect | adaptive
-status: pending | in-progress | done | failed
-order: 1
-skills: []
-depends_on: []
+role: backend-engineer | frontend-engineer | architect | adaptive                                                                                                                                             
+status: pending | in-progress | done | failed                                                                                                                                                               
+order: 1                                                                                                                                                                                                      
+complexity: standard          # trivial | quick | standard | complex — conductor uses this for model selection                                                                                                          
+skills: []                                                                                                                                                                                                    
+depends_on: []   
 ---
 
 ## Objective

package/template/CLAUDE.md

@@ -23,6 +23,7 @@ Call `ask_user_questions` with:
   7. Discussion — Just brainstorm, no role needed
 
 If user skips or starts giving instructions directly — work with them normally.
+Sub-agents spawned by conductor skip role selection — they already have a role assigned in their prompt.
 Do NOT greet. Do NOT explain. The role selection IS your greeting.
 
 **AFTER ROLE SELECTED:**