@sulhadin/orchestrator 3.0.0-beta → 3.0.0-beta.10

package/README.md

@@ -1,6 +1,12 @@
 # Orchestra
 
-AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Two terminals — PM plans, conductor builds.
+AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). One terminal plans, another builds — from idea to production.
+
+## What is Orchestra?
+
+Orchestra turns a single Claude Code session into a coordinated development team. A Product Manager plans features, a Conductor executes them — switching between specialized roles (backend, frontend, architect) automatically. Each role has strict boundaries, every commit passes verification, and the system learns from past milestones.
+
+No infrastructure. No API keys. Just markdown files and Claude Code.
 
 ## Install
 
@@ -8,79 +14,139 @@ AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claud
 npx @sulhadin/orchestrator
 ```
 
-## Two Terminals
-
-### Terminal 1: `/orchestra pm` — Planning
+This installs `.orchestra/` (project data + config) and `.claude/` (agents, skills, rules, commands) into your project.
 
-PM is your strategic partner. Discuss ideas, challenge scope, create milestones.
+## How It Works
 
 ```
-You: /orchestra pm
-PM:  "No active milestones. What's on your mind?"
-
-You: "I want user authentication with JWT"
-PM:  *discusses, challenges, creates milestone with phases*
+Terminal 1 (PM):                    Terminal 2 (Conductor):
+  /orchestra pm                       /orchestra start
+  │                                   │
+  ├─ Discuss features                 ├─ Scan milestones
+  ├─ Create milestones                ├─ Activate architect → RFC
+  ├─ Groom phases                     ├─ Activate backend → code + tests
+  │                                   ├─ Activate frontend → UI
+  │  (plan M2 while M1 runs)          ├─ Call reviewer → code review
+  │                                   ├─ Push → milestone done
+  │                                   └─ Loop → next milestone
 ```
 
-### Terminal 2: `/orchestra start` — Execution
-
-Conductor picks up milestones and executes them autonomously.
+## Quick Example
 
+**Terminal 1:**
+```
+/orchestra pm
+> "I want user authentication with JWT"
+PM challenges scope, creates M1-user-auth with 3 phases
 ```
-You: /orchestra start
 
+**Terminal 2:**
+```
+/orchestra start
 📋 Starting M1-user-auth
-🏗️ architect ▶ RFC...         ✅ done
-⚙️ backend ▶ DB schema...     ✅ done
-⚙️ backend ▶ API endpoints... ✅ done
-🎨 frontend ▶ Login UI...     ✅ done
-🔍 reviewer ▶ reviewing...    ✅ approved
+🏗️ architect → RFC ready → user approves
+⚙️ backend → phase-1: DB schema → committed
+⚙️ backend → phase-2: API endpoints → committed
+🎨 frontend → phase-3: Login UI → committed
+🔍 reviewer → approved
 🚦 Push? → yes
-✅ M1-user-auth done.
-
-📋 Starting M2-dashboard...
+✅ M1-user-auth done. Checking for next milestone...
 ```
 
 ## Commands
 
+### Pipeline
 | Command | What it does |
 |---------|-------------|
-| `/orchestra pm` | Plan features, create milestones |
-| `/orchestra start` | Execute milestones (asks at approval gates) |
-| `/orchestra start --auto` | Fully autonomous |
+| `/orchestra pm` | Open PM terminal — plan features, create milestones |
+| `/orchestra start` | Execute milestones autonomously (asks at approval gates) |
+| `/orchestra start --auto` | Fully autonomous — warns once, then auto-push |
 | `/orchestra hotfix {desc}` | Ultra-fast fix: implement → verify → commit → push |
-| `/orchestra status` | Milestone status report |
+| `/orchestra status` | Milestone status report (PM only) |
 | `/orchestra blueprint {name}` | Generate milestones from template |
+| `/orchestra blueprint add` | Save current work as reusable template |
+| `/orchestra create-role` | Create a new role interactively (Orchestrator only) |
 | `/orchestra help` | Show all commands |
 
+### Roles
+| Command | Role |
+|---------|------|
+| `/orchestra pm` | Product Manager — plan and orchestrate |
+| `/orchestra backend` | Backend Engineer — code + tests |
+| `/orchestra frontend` | Frontend Engineer — UI + design |
+| `/orchestra architect` | Architect — technical design |
+| `/orchestra adaptive` | Adaptive expert — any domain (iOS, DevOps, ML...) |
+| `/orchestra orchestrator` | System maintenance |
+
 ## Architecture
 
 ```
-.claude/                              ← Claude Code integration
-├── agents/conductor.md               ← Autonomous executor
-├── agents/reviewer.md                ← Independent code review
-├── skills/*.orchestra.md             ← 14 domain checklists
-├── rules/*.orchestra.md              ← Discipline rules
-└── commands/orchestra/               ← /orchestra commands
-
-.orchestra/                           ← Project data + config
-├── config.yml                        ← Pipeline settings (customize per stack)
-├── roles/                            ← Role identities (slim)
-├── blueprints/                       ← Project templates
-├── knowledge.md                      ← Project knowledge log
-└── milestones/                       ← Your work
+.claude/                                ← Claude Code integration
+├── agents/
+│   ├── conductor.md                    ← Autonomous milestone executor
+│   └── reviewer.md                     ← Independent code review
+├── skills/*.orchestra.md               ← 14 domain checklists
+├── rules/*.orchestra.md                ← 8 discipline rules
+└── commands/orchestra/                 ← /orchestra commands
+
+.orchestra/                             ← Project data + config
+├── config.yml                          ← Pipeline settings (customize per stack)
+├── roles/                              ← Role identities
+├── blueprints/                         ← Project templates
+├── knowledge.md                        ← Project knowledge log
+└── milestones/                         ← Your work
+```
+
+## Key Features
+
+**Config-driven pipeline** — `.orchestra/config.yml` controls everything: verification commands (customize for Go, Python, Rust), approval gates, thresholds, parallel execution. No hardcoded assumptions.
+
+**Three complexity levels** — PM sets per milestone:
+- `quick` → Engineer → Commit → Push (trivial changes)
+- `standard` → Engineer → Review → Push (typical features)
+- `full` → Architect → Engineer → Review → Push (complex work)
+
+**Verification gate** — Tests + lint must pass before every commit. Commands come from config. Fails 3 times → phase marked failed, escalated to user.
+
+**14 built-in skills** — Domain checklists for auth, CRUD, deployment, accessibility, React, testing, debugging, and more. PM assigns to phases, conductor loads them automatically.
+
+**Blueprints** — Start from templates instead of scratch. `saas-starter` creates 5 milestones instantly. `blueprint add` saves your work as a reusable template.
+
+**Learning system** — `knowledge.md` accumulates decisions and lessons. 5-line retrospective after each milestone. PM reads before grooming new work. System gets smarter over time.
+
+**Role boundaries** — Enforced via `.claude/rules/`. PM cannot write code. Engineers cannot modify system files. Orchestrator cannot write features. Boundaries checked by file path, not by words.
+
+**Stuck detection** — Detects repeated failures, circular fixes, over-engineering. Tries different approach once, then escalates. Auto mode skips to next phase.
+
+## Upgrading
+
+```bash
+npx @sulhadin/orchestrator
 ```
 
+Smart merge on upgrade:
+
+| What | On upgrade |
+|------|-----------|
+| System files (roles, rules, agents, commands) | Updated to latest |
+| Skills (`.orchestra.md`) | Updated |
+| Skills (your custom `.md`) | Preserved |
+| Blueprints (template) | Updated |
+| Blueprints (your custom) | Preserved |
+| milestones/ | Untouched |
+| knowledge.md | Preserved |
+| config.yml | Preserved |
+
 ## Documentation
 
-See [docs/](https://github.com/sulhadin/orchestrator/blob/main/docs/README.md) for full documentation:
+Full docs at [docs/](https://github.com/sulhadin/orchestrator/blob/main/docs/README.md):
 
-- [Getting Started](https://github.com/sulhadin/orchestrator/blob/main/docs/getting-started.md)
-- [Commands](https://github.com/sulhadin/orchestrator/blob/main/docs/commands.md)
-- [Roles](https://github.com/sulhadin/orchestrator/blob/main/docs/roles.md)
-- [Features](https://github.com/sulhadin/orchestrator/blob/main/docs/features.md)
-- [Blueprints](https://github.com/sulhadin/orchestrator/blob/main/docs/blueprints.md)
-- [Skills](https://github.com/sulhadin/orchestrator/blob/main/docs/skills.md)
+- [Getting Started](https://github.com/sulhadin/orchestrator/blob/main/docs/getting-started.md) — installation, first milestone, two-terminal model
+- [Commands](https://github.com/sulhadin/orchestrator/blob/main/docs/commands.md) — all commands with examples
+- [Roles](https://github.com/sulhadin/orchestrator/blob/main/docs/roles.md) — 6 roles + adaptive, responsibilities, boundaries
+- [Features](https://github.com/sulhadin/orchestrator/blob/main/docs/features.md) — config, verification, skills, blueprints, and more
+- [Blueprints](https://github.com/sulhadin/orchestrator/blob/main/docs/blueprints.md) — project templates, customization
+- [Skills](https://github.com/sulhadin/orchestrator/blob/main/docs/skills.md) — domain checklists, creating new skills
 
 ## License
 

package/bin/build-template.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const rootDir = process.cwd();
+const templateDir = path.join(rootDir, "template");
+
+// System files to include in the template
+const SYSTEM_PATHS = [
+  { src: ".claude/agents", dest: ".claude/agents" },
+  { src: ".claude/commands/orchestra", dest: ".claude/commands/orchestra" },
+  { src: ".claude/rules", dest: ".claude/rules", filter: (f) => f.endsWith(".orchestra.md") },
+  { src: ".claude/skills", dest: ".claude/skills", filter: (f) => f.endsWith(".orchestra.md") },
+  { src: ".orchestra/roles", dest: ".orchestra/roles" },
+  { src: ".orchestra/blueprints", dest: ".orchestra/blueprints" },
+  { src: ".orchestra/config.yml", dest: ".orchestra/config.yml" },
+  { src: ".orchestra/knowledge.md", dest: ".orchestra/knowledge.md" },
+  { src: ".orchestra/README.md", dest: ".orchestra/README.md" },
+  { src: "CLAUDE.md", dest: "CLAUDE.md" }
+];
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function copyRecursive(src, dest, filter = null) {
+  const fullSrc = path.join(rootDir, src);
+  const fullDest = path.join(templateDir, dest);
+
+  if (!fs.existsSync(fullSrc)) {
+    console.warn(`  [!] Source not found, skipping: ${src}`);
+    return;
+  }
+
+  const stat = fs.statSync(fullSrc);
+
+  if (stat.isDirectory()) {
+    ensureDir(fullDest);
+    const entries = fs.readdirSync(fullSrc, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      if (filter && !filter(entry.name)) continue;
+      
+      const entrySrc = path.join(src, entry.name);
+      const entryDest = path.join(dest, entry.name);
+      
+      const fullEntrySrc = path.join(rootDir, entrySrc);
+      const fullEntryDest = path.join(templateDir, entryDest);
+
+      if (entry.isSymbolicLink()) {
+        const linkTarget = fs.readlinkSync(fullEntrySrc);
+        if (fs.existsSync(fullEntryDest)) fs.unlinkSync(fullEntryDest);
+        fs.symlinkSync(linkTarget, fullEntryDest);
+      } else if (entry.isDirectory()) {
+        copyRecursive(entrySrc, entryDest, filter);
+      } else {
+        fs.copyFileSync(fullEntrySrc, fullEntryDest);
+      }
+    }
+  } else {
+    ensureDir(path.dirname(fullDest));
+    fs.copyFileSync(fullSrc, fullDest);
+  }
+}
+
+console.log("\n  Orchestra — Template Builder");
+console.log("  Packing root system files into template/...\n");
+
+for (const item of SYSTEM_PATHS) {
+  copyRecursive(item.src, item.dest, item.filter);
+  console.log(`  [+] Packed: ${item.src}`);
+}
+
+console.log("\n  Done! Template is updated and ready for release.");
+console.log("  Run 'yarn build' to test the installation from this template.\n");

package/bin/index.js

@@ -39,8 +39,8 @@ function parseArgs() {
         flags.help = true;
         break;
       default:
-        console.error("  Unknown flag: " + arg);
-        process.exit(1);
+        // Ignore files passed by lint-staged or other tools
+        break;
     }
   }
 
@@ -71,6 +71,10 @@ function copyDirRecursive(src, dest) {
     const destPath = path.join(dest, entry.name);
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath);
+    } else if (entry.isSymbolicLink()) {
+      const linkTarget = fs.readlinkSync(srcPath);
+      if (fs.existsSync(destPath)) fs.unlinkSync(destPath);
+      fs.symlinkSync(linkTarget, destPath);
     } else {
       fs.copyFileSync(srcPath, destPath);
     }
@@ -91,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;
@@ -298,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/package.json

@@ -1,9 +1,18 @@
 {
   "name": "@sulhadin/orchestrator",
-  "version": "3.0.0-beta",
+  "version": "3.0.0-beta.10",
   "description": "AI Team Orchestration System — multi-role coordination for Claude Code",
-  "bin": {
-    "orchestrator": "bin/index.js"
+  "bin": "bin/index.js",
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "template": "node bin/build-template.js",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "**/*.{js,md,yml,json}": [
+      "yarn template",
+      "yarn build"
+    ]
   },
   "files": [
     "bin/",
@@ -15,7 +24,8 @@
     "ai",
     "agent",
     "multi-agent",
-    "claude-code"
+    "claude-code",
+    "team"
   ],
   "repository": {
     "type": "git",
@@ -27,5 +37,9 @@
   },
   "author": "Sulhadin Öney",
   "license": "MIT",
-  "packageManager": "yarn@4.13.0"
+  "packageManager": "yarn@4.13.0",
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0"
+  }
 }