@sulhadin/orchestrator 2.0.0 → 3.0.0-beta

package/README.md

@@ -1,111 +1,86 @@
 # Orchestra
 
-AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Two terminals — PM plans, worker builds.
+AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Two terminals — PM plans, conductor builds.
 
 ## Install
 
 ```bash
-npx @sulhadin/orchestrator@latest
-```
-
-Skip permission prompts:
-
-```bash
-npx @sulhadin/orchestrator@latest --dangerously-skip-permissions
+npx @sulhadin/orchestrator
 ```
 
 ## Two Terminals
 
-### Terminal 1: `#pm` — Planning
+### Terminal 1: `/orchestra pm` — Planning
 
-PM is your strategic partner. Discuss ideas, challenge scope, create milestones. PM never writes code — only plans.
+PM is your strategic partner. Discuss ideas, challenge scope, create milestones.
 
 ```
-You: #pm
-PM:  "No active milestones. Ready for instructions."
+You: /orchestra pm
+PM:  "No active milestones. What's on your mind?"
 
 You: "I want user authentication with JWT"
-PM:  *discusses, challenges, refines scope*
-
-You: "Create the milestone"
-PM:  *creates prd.md, grooming.md, milestone.md, phases/*
-     "🎯 M1-user-auth ready. Run #start in another terminal."
-
-You: "Let's also plan a dashboard"
-PM:  *plans M2 while worker executes M1*
+PM:  *discusses, challenges, creates milestone with phases*
 ```
 
-PM is always available. Plan ahead while work runs in the other terminal.
-
-### Terminal 2: `#start` — Execution
+### Terminal 2: `/orchestra start` — Execution
 
-Worker picks up milestones and executes them autonomously. Loops to the next when done.
+Conductor picks up milestones and executes them autonomously.
 
 ```
-You: #start
+You: /orchestra start
 
 📋 Starting M1-user-auth
-
-🏗️ #architect ▶ RFC + grooming validation...
-🏗️ #architect ✅ RFC ready
-🚦 Approve RFC? → yes
-
-⚙️ #backend ▶ phase-1: DB schema + migrations...
-⚙️ #backend ✅ phase-1 done (feat(db): add auth tables)
-
-⚙️ #backend ▶ phase-2: API endpoints + tests...
-⚙️ #backend ✅ phase-2 done (feat(auth): add login endpoint)
-
-🎨 #frontend ▶ phase-3: Login UI...
-🎨 #frontend ✅ phase-3 done (feat(auth): add login page)
-
-🔍 #reviewer ▶ reviewing unpushed commits...
-🔍 #reviewer ✅ approved
-
-🚦 Push to origin? → yes
+🏗️ architect ▶ RFC...         ✅ done
+⚙️ backend ▶ DB schema...     ✅ done
+⚙️ backend ▶ API endpoints... ✅ done
+🎨 frontend ▶ Login UI...     ✅ done
+🔍 reviewer ▶ reviewing...    ✅ approved
+🚦 Push? → yes
 ✅ M1-user-auth done.
 
 📋 Starting M2-dashboard...
 ```
 
-Close the terminal, reopen, type `#start` — it resumes from where it left off.
-
 ## Commands
 
-| Command | Where | What it does |
-|---------|-------|-------------|
-| `#pm` | Terminal 1 | Plan features, create milestones |
-| `#start` | Terminal 2 | Execute milestones, asks at approval gates |
-| `#start --auto` | Terminal 2 | Confirms once, then fully autonomous |
-| `#hotfix {desc}` | Any | Ultra-fast fix: implement → verify → commit → push |
-| `#status` | Terminal 1 | Milestone status report |
-| `#help` | Any | Show all commands |
-| `#help skills` | Any | List available skills |
-| `#help blueprints` | Any | List available blueprints |
-| `#blueprint {name}` | Terminal 1 | Generate milestones from template |
-| `#blueprint add` | Terminal 1 | Save current work as reusable template |
-
-Manual roles (any terminal):
-
-| Command | Role |
-|---------|------|
-| `#backend` | Backend Engineer |
-| `#frontend` | Frontend Engineer |
-| `#reviewer` | Code Reviewer |
-| `#architect` | Architect |
-| `#owner` | System maintenance |
-| `#adaptive` | Adaptive expert (iOS, DevOps, ML, etc.) |
+| Command | What it does |
+|---------|-------------|
+| `/orchestra pm` | Plan features, create milestones |
+| `/orchestra start` | Execute milestones (asks at approval gates) |
+| `/orchestra start --auto` | Fully autonomous |
+| `/orchestra hotfix {desc}` | Ultra-fast fix: implement → verify → commit → push |
+| `/orchestra status` | Milestone status report |
+| `/orchestra blueprint {name}` | Generate milestones from template |
+| `/orchestra help` | Show all commands |
+
+## 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
+```
 
 ## Documentation
 
 See [docs/](https://github.com/sulhadin/orchestrator/blob/main/docs/README.md) for full documentation:
 
-- [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) — 7 roles, responsibilities, boundaries
-- [Features](https://github.com/sulhadin/orchestrator/blob/main/docs/features.md) — verification gate, fast track, parallel, hotfix, and more
-- [Blueprints](https://github.com/sulhadin/orchestrator/blob/main/docs/blueprints.md) — project templates, `#blueprint add`
-- [Skills](https://github.com/sulhadin/orchestrator/blob/main/docs/skills.md) — domain checklists, creating new skills
+- [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)
 
 ## License
 

package/bin/index.js

@@ -9,7 +9,9 @@ const templateDir = path.join(__dirname, "..", "template");
 const ORCHESTRA_SECTION_START = "<!-- orchestra -->";
 const ORCHESTRA_SECTION_END = "<!-- /orchestra -->";
 
-const USER_DIRS = ["milestones", "skills", "blueprints"];
+// User directories to preserve during upgrade
+const ORCHESTRA_USER_DIRS = ["milestones", "blueprints"];
+const CLAUDE_USER_DIRS = ["skills", "rules"];
 
 const ALLOW_PERMISSIONS = [
   "Bash(*)",
@@ -25,10 +27,7 @@ const ALLOW_PERMISSIONS = [
 
 function parseArgs() {
   const args = process.argv.slice(2);
-  const flags = {
-    skipPermissions: false,
-    help: false,
-  };
+  const flags = { skipPermissions: false, help: false };
 
   for (const arg of args) {
     switch (arg) {
@@ -53,7 +52,7 @@ function showHelp() {
   console.log("  Usage: npx @sulhadin/orchestrator [options]");
   console.log("");
   console.log("  Options:");
-  console.log("    --dangerously-skip-permissions   Auto-allow all tool permissions (no y/n prompts)");
+  console.log("    --dangerously-skip-permissions   Auto-allow all tool permissions");
   console.log("    --help, -h                       Show this help");
   console.log("");
   console.log("  Examples:");
@@ -66,13 +65,10 @@ function copyDirRecursive(src, dest) {
   if (!fs.existsSync(dest)) {
     fs.mkdirSync(dest, { recursive: true });
   }
-
   const entries = fs.readdirSync(src, { withFileTypes: true });
-
   for (const entry of entries) {
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
-
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath);
     } else {
@@ -83,9 +79,7 @@ function copyDirRecursive(src, dest) {
 
 function rmDirRecursive(dir) {
   if (!fs.existsSync(dir)) return;
-
   const entries = fs.readdirSync(dir, { withFileTypes: true });
-
   for (const entry of entries) {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
@@ -94,21 +88,47 @@ function rmDirRecursive(dir) {
       fs.unlinkSync(fullPath);
     }
   }
-
   fs.rmdirSync(dir);
 }
 
 function extractOrchestraSection(content) {
   const startIdx = content.indexOf(ORCHESTRA_SECTION_START);
   if (startIdx === -1) return null;
-
   const endIdx = content.indexOf(ORCHESTRA_SECTION_END, startIdx);
-  if (endIdx === -1) {
-    return content.slice(startIdx);
-  }
+  if (endIdx === -1) return content.slice(startIdx);
   return content.slice(startIdx, endIdx + ORCHESTRA_SECTION_END.length);
 }
 
+/**
+ * Smart merge for user directories (skills, rules, blueprints):
+ * - .orchestra.md files = system files → always updated from template
+ * - other .md files = user files → preserved
+ */
+function smartMergeDir(backupPath, restorePath, templateDirPath) {
+  const templateFiles = fs.existsSync(templateDirPath)
+    ? fs.readdirSync(templateDirPath)
+    : [];
+  const backupFiles = fs.readdirSync(backupPath).filter((f) => f !== ".gitkeep");
+  let restored = 0;
+
+  for (const file of backupFiles) {
+    // User-created files: not in template AND not .orchestra.md
+    const isOrchestraFile = file.endsWith(".orchestra.md");
+    if (!templateFiles.includes(file) && !isOrchestraFile) {
+      const srcFile = path.join(backupPath, file);
+      const destFile = path.join(restorePath, file);
+      if (fs.statSync(srcFile).isDirectory()) {
+        copyDirRecursive(srcFile, destFile);
+      } else {
+        fs.copyFileSync(srcFile, destFile);
+      }
+      restored++;
+    }
+  }
+
+  return restored;
+}
+
 function setupPermissions() {
   const claudeDir = path.join(targetDir, ".claude");
   const settingsPath = path.join(claudeDir, "settings.local.json");
@@ -126,10 +146,7 @@ function setupPermissions() {
     }
   }
 
-  if (!settings.permissions) {
-    settings.permissions = {};
-  }
-
+  if (!settings.permissions) settings.permissions = {};
   const existing = settings.permissions.allow || [];
   const merged = [...new Set([...existing, ...ALLOW_PERMISSIONS])];
   settings.permissions.allow = merged;
@@ -138,7 +155,7 @@ function setupPermissions() {
 
   const added = merged.length - existing.length;
   if (added > 0) {
-    console.log("  [+] Permissions configured (" + added + " rules added to .claude/settings.local.json)");
+    console.log("  [+] Permissions configured (" + added + " rules added)");
   } else {
     console.log("  [~] Permissions already configured");
   }
@@ -146,7 +163,6 @@ function setupPermissions() {
 
 function run() {
   const flags = parseArgs();
-
   if (flags.help) {
     showHelp();
     return;
@@ -158,87 +174,118 @@ function run() {
   console.log("");
 
   const orchestraSrc = path.join(templateDir, ".orchestra");
+  const claudeSrc = path.join(templateDir, ".claude");
   const orchestraDest = path.join(targetDir, ".orchestra");
+  const claudeDest = path.join(targetDir, ".claude");
   const isUpgrade = fs.existsSync(orchestraDest);
 
   if (isUpgrade) {
+    // ── Backup user data ──
     const backups = {};
 
-    for (const dir of USER_DIRS) {
+    // .orchestra/ user dirs (milestones, blueprints)
+    for (const dir of ORCHESTRA_USER_DIRS) {
       const dirPath = path.join(orchestraDest, dir);
       const backupPath = path.join(targetDir, ".orchestra-backup-" + dir);
+      if (fs.existsSync(dirPath)) {
+        const files = fs.readdirSync(dirPath).filter((f) => f !== ".gitkeep");
+        if (files.length > 0) {
+          copyDirRecursive(dirPath, backupPath);
+          backups["orchestra:" + dir] = { backupPath, type: "orchestra", dir };
+          console.log("  [~] Backed up .orchestra/" + dir + "/ (" + files.length + " items)");
+        }
+      }
+    }
 
+    // .claude/ user dirs (skills, rules — user may have added custom ones)
+    for (const dir of CLAUDE_USER_DIRS) {
+      const dirPath = path.join(claudeDest, dir);
+      const backupPath = path.join(targetDir, ".claude-backup-" + dir);
       if (fs.existsSync(dirPath)) {
         const files = fs.readdirSync(dirPath).filter((f) => f !== ".gitkeep");
         if (files.length > 0) {
           copyDirRecursive(dirPath, backupPath);
-          backups[dir] = backupPath;
-          console.log("  [~] Backed up " + dir + "/ (" + files.length + " items)");
+          backups["claude:" + dir] = { backupPath, type: "claude", dir };
+          console.log("  [~] Backed up .claude/" + dir + "/ (" + files.length + " items)");
         }
       }
     }
 
-    // Backup knowledge.md (single file, not a directory)
-    const knowledgeSrc = path.join(orchestraDest, "knowledge.md");
+    // knowledge.md
+    const knowledgePath = path.join(orchestraDest, "knowledge.md");
     const knowledgeBackup = path.join(targetDir, ".orchestra-backup-knowledge.md");
     let hasKnowledge = false;
-    if (fs.existsSync(knowledgeSrc)) {
-      const content = fs.readFileSync(knowledgeSrc, "utf-8");
-      // Backup if there are any entries after the "Active Knowledge" marker
-      const activeMarker = "<!-- New entries go here";
-      const markerIdx = content.indexOf(activeMarker);
-      const hasEntries = markerIdx !== -1 && content.slice(markerIdx + activeMarker.length).trim().length > 10;
-      if (hasEntries) {
-        fs.copyFileSync(knowledgeSrc, knowledgeBackup);
+    if (fs.existsSync(knowledgePath)) {
+      const content = fs.readFileSync(knowledgePath, "utf-8");
+      const marker = "<!-- New entries go here";
+      const idx = content.indexOf(marker);
+      if (idx !== -1 && content.slice(idx + marker.length).trim().length > 10) {
+        fs.copyFileSync(knowledgePath, knowledgeBackup);
         hasKnowledge = true;
-        console.log("  [~] Backed up knowledge.md (has project entries)");
+        console.log("  [~] Backed up knowledge.md");
       }
     }
 
+    // config.yml (user may have customized)
+    const configPath = path.join(orchestraDest, "config.yml");
+    const configBackup = path.join(targetDir, ".orchestra-backup-config.yml");
+    let hasConfig = false;
+    if (fs.existsSync(configPath)) {
+      fs.copyFileSync(configPath, configBackup);
+      hasConfig = true;
+      console.log("  [~] Backed up config.yml");
+    }
+
+    // ── Clean install ──
     rmDirRecursive(orchestraDest);
     console.log("  [~] Removed old .orchestra/");
 
+    // Remove old .claude/ orchestra files (agents, commands) but keep user files
+    const claudeOrchestraDirs = ["agents", "commands"];
+    for (const dir of claudeOrchestraDirs) {
+      const dirPath = path.join(claudeDest, dir);
+      if (fs.existsSync(dirPath)) {
+        // Only remove orchestra files, keep user's custom agents/commands
+        const files = fs.readdirSync(dirPath);
+        for (const file of files) {
+          if (file === "conductor.md" || file === "reviewer.md" || file === "orchestra") {
+            const fullPath = path.join(dirPath, file);
+            if (fs.statSync(fullPath).isDirectory()) {
+              rmDirRecursive(fullPath);
+            } else {
+              fs.unlinkSync(fullPath);
+            }
+          }
+        }
+      }
+    }
+
     copyDirRecursive(orchestraSrc, orchestraDest);
-    console.log("  [+] .orchestra/ installed (clean)");
+    console.log("  [+] .orchestra/ installed");
 
-    for (const [dir, backupPath] of Object.entries(backups)) {
-      const restorePath = path.join(orchestraDest, dir);
-      const templateDirPath = path.join(orchestraSrc, dir);
+    if (fs.existsSync(claudeSrc)) {
+      copyDirRecursive(claudeSrc, claudeDest);
+      console.log("  [+] .claude/ orchestra files installed");
+    }
+
+    // ── Restore user data ──
+    for (const [key, { backupPath, type, dir }] of Object.entries(backups)) {
+      const baseDest = type === "orchestra" ? orchestraDest : claudeDest;
+      const restorePath = path.join(baseDest, dir);
+      const templateDirPath = type === "orchestra"
+        ? path.join(orchestraSrc, dir)
+        : path.join(claudeSrc, dir);
 
       if (dir === "milestones") {
-        // Milestones are fully user-owned — restore everything
-        if (fs.existsSync(restorePath)) {
-          rmDirRecursive(restorePath);
-        }
+        if (fs.existsSync(restorePath)) rmDirRecursive(restorePath);
         copyDirRecursive(backupPath, restorePath);
-        console.log("  [+] Restored " + dir + "/");
+        console.log("  [+] Restored milestones/");
       } else {
-        // Skills & blueprints: template files get updated, user-created files are preserved
-        // Template files are already in place from clean install.
-        // Only copy back files that DON'T exist in template (user-created).
-        const templateFiles = fs.existsSync(templateDirPath)
-          ? fs.readdirSync(templateDirPath)
-          : [];
-        const backupFiles = fs.readdirSync(backupPath).filter((f) => f !== ".gitkeep");
-        let restored = 0;
-
-        for (const file of backupFiles) {
-          if (!templateFiles.includes(file)) {
-            const srcFile = path.join(backupPath, file);
-            const destFile = path.join(restorePath, file);
-            if (fs.statSync(srcFile).isDirectory()) {
-              copyDirRecursive(srcFile, destFile);
-            } else {
-              fs.copyFileSync(srcFile, destFile);
-            }
-            restored++;
-          }
-        }
-
+        const restored = smartMergeDir(backupPath, restorePath, templateDirPath);
         if (restored > 0) {
-          console.log("  [+] Restored " + restored + " user-created files in " + dir + "/");
+          console.log("  [+] Restored " + restored + " user files in " + dir + "/");
         }
-        console.log("  [~] Updated template files in " + dir + "/");
+        console.log("  [~] Updated system files in " + dir + "/");
       }
 
       rmDirRecursive(backupPath);
@@ -250,16 +297,26 @@ function run() {
       fs.unlinkSync(knowledgeBackup);
       console.log("  [+] Restored knowledge.md");
     }
+
+    // Restore config.yml (user's customizations take priority)
+    if (hasConfig && fs.existsSync(configBackup)) {
+      fs.copyFileSync(configBackup, path.join(orchestraDest, "config.yml"));
+      fs.unlinkSync(configBackup);
+      console.log("  [+] Restored config.yml (user customizations preserved)");
+    }
   } else {
+    // ── Fresh install ──
     copyDirRecursive(orchestraSrc, orchestraDest);
     console.log("  [+] .orchestra/ installed");
+
+    if (fs.existsSync(claudeSrc)) {
+      copyDirRecursive(claudeSrc, claudeDest);
+      console.log("  [+] .claude/ installed");
+    }
   }
 
-  // Handle CLAUDE.md
-  const templateClaudeMd = fs.readFileSync(
-    path.join(templateDir, "CLAUDE.md"),
-    "utf-8"
-  );
+  // ── Handle CLAUDE.md ──
+  const templateClaudeMd = fs.readFileSync(path.join(templateDir, "CLAUDE.md"), "utf-8");
   const targetClaudeMdPath = path.join(targetDir, "CLAUDE.md");
 
   if (fs.existsSync(targetClaudeMdPath)) {
@@ -274,15 +331,11 @@ function run() {
     if (existingContent.includes(ORCHESTRA_SECTION_START)) {
       const existingSection = extractOrchestraSection(existingContent);
       if (existingSection) {
-        existingContent = existingContent.replace(
-          existingSection,
-          orchestraSection
-        );
+        existingContent = existingContent.replace(existingSection, orchestraSection);
       }
       console.log("  [~] CLAUDE.md updated (Orchestra section replaced)");
     } else {
-      existingContent =
-        existingContent.trimEnd() + "\n\n" + orchestraSection + "\n";
+      existingContent = existingContent.trimEnd() + "\n\n" + orchestraSection + "\n";
       console.log("  [+] CLAUDE.md updated (Orchestra section appended)");
     }
 
@@ -292,7 +345,7 @@ function run() {
     console.log("  [+] CLAUDE.md created");
   }
 
-  // Handle permissions
+  // ── Handle permissions ──
   if (flags.skipPermissions) {
     setupPermissions();
   }
@@ -302,7 +355,8 @@ function run() {
   console.log("");
   console.log("  Next steps:");
   console.log("    1. Open Claude Code in your project");
-  console.log('    2. Say "#pm" to start orchestrating');
+  console.log('    2. Type "/orchestra pm" to start planning');
+  console.log('    3. Type "/orchestra start" in another terminal to execute');
   console.log("");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sulhadin/orchestrator",
-  "version": "2.0.0",
+  "version": "3.0.0-beta",
   "description": "AI Team Orchestration System — multi-role coordination for Claude Code",
   "bin": {
     "orchestrator": "bin/index.js"