@sulhadin/orchestrator 3.1.1 → 3.1.3

package/bin/build-template.js

@@ -14,6 +14,9 @@ const DEV_ONLY_AGENTS = new Set([
   "repo-deep-analyzer.md",
 ]);
 
+// Dev-only skills that should NOT be published to users
+const DEV_ONLY_SKILLS = new Set(["ship"]);
+
 // Plugin manifest
 const PLUGIN_MANIFEST = {
   name: "orchestra",
@@ -31,7 +34,11 @@ const SYSTEM_PATHS = [
   { src: ".claude/agents", dest: "agents", filter: (f) => !DEV_ONLY_AGENTS.has(f) },
   { src: ".claude/commands/orchestra", dest: "commands" },
   { src: ".claude/rules", dest: "rules", filter: (f) => f.endsWith(".orchestra.md") },
-  { src: ".claude/skills", dest: "skills", filter: (f) => f.endsWith(".orchestra.md") },
+  { src: ".claude/skills", dest: "skills", filter: (f) => {
+    if (DEV_ONLY_SKILLS.has(f)) return false;
+    const skillDir = path.join(rootDir, ".claude/skills", f);
+    return fs.statSync(skillDir).isDirectory() && fs.existsSync(path.join(skillDir, "SKILL.md"));
+  }},
   { src: ".orchestra/roles", dest: ".orchestra/roles" },
   { src: ".orchestra/blueprints", dest: ".orchestra/blueprints" },
   { src: ".orchestra/config.yml", dest: ".orchestra/config.yml" },
@@ -75,7 +82,7 @@ function copyRecursive(src, dest, filter = null) {
         if (fs.existsSync(fullEntryDest)) fs.unlinkSync(fullEntryDest);
         fs.symlinkSync(linkTarget, fullEntryDest);
       } else if (entry.isDirectory()) {
-        copyRecursive(entrySrc, entryDest, filter);
+        copyRecursive(entrySrc, entryDest);
       } else {
         fs.copyFileSync(fullEntrySrc, fullEntryDest);
       }

package/bin/index.js

@@ -230,8 +230,8 @@ function extractOrchestraSection(content) {
 
 /**
  * Smart merge for user directories (skills, rules, blueprints):
- * - .orchestra.md files = system files → always updated from template
- * - other .md files = user files → preserved
+ * - entries present in template = system files → always updated from template
+ * - entries not in template = user files → preserved
  */
 function smartMergeDir(backupPath, restorePath, templateDirPath) {
   const templateFiles = fs.existsSync(templateDirPath)
@@ -241,9 +241,8 @@ function smartMergeDir(backupPath, restorePath, templateDirPath) {
   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) {
+    // User-created entries: not in template → preserve
+    if (!templateFiles.includes(file)) {
       const srcFile = path.join(backupPath, file);
       const destFile = path.join(restorePath, file);
       if (fs.statSync(srcFile).isDirectory()) {

package/package.json

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

package/template/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "orchestra",
   "description": "AI Team Orchestration — multi-role coordination with milestones, phases, and quality gates for Claude Code",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "author": {
     "name": "Sulhadin Öney"
   },

package/template/.orchestra/README.md

@@ -262,7 +262,7 @@ No role may create, edit, delete, or modify these files:
 - `.orchestra/blueprints/`
 - `.claude/agents/conductor.md`, `.claude/agents/reviewer.md`
 - `.claude/rules/*.orchestra.md`
-- `.claude/skills/*.orchestra.md`
+- `.claude/skills/*/SKILL.md`
 - `.claude/commands/orchestra/`
 - `CLAUDE.md`
 - `docs/`
@@ -288,7 +288,7 @@ Each role has exclusive write access to specific directories:
 
 | Role | Owns (can write) | Reads |
 |------|-------------------|-------|
-| orchestrator | `.orchestra/roles/*`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `CLAUDE.md`, `.claude/agents/`, `.claude/skills/*.orchestra.md`, `.claude/rules/*.orchestra.md`, `.claude/commands/orchestra/`, `.orchestra/knowledge.md`, `docs/` | Everything |
+| orchestrator | `.orchestra/roles/*`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `CLAUDE.md`, `.claude/agents/`, `.claude/skills/*/SKILL.md`, `.claude/rules/*.orchestra.md`, `.claude/commands/orchestra/`, `.orchestra/knowledge.md`, `docs/` | Everything |
 | product-manager | `.orchestra/milestones/*` (prd.md, milestone.md, grooming.md, phases) | Everything |
 | architect | `.orchestra/milestones/*/rfc.md`, `.orchestra/milestones/*/architecture.md`, `.orchestra/milestones/*/adrs/*`, project configs | Everything |
 | backend-engineer | Defined by PM in phase scope (typically `src/`, `tests/`, `migrations/`) | `.orchestra/milestones/*/phases/*` |

package/template/.orchestra/roles/orchestrator.md

@@ -21,7 +21,7 @@ You are NOT above the system — you ARE the system.
 | Edit CLAUDE.md | `CLAUDE.md` |
 | Edit conductor/reviewer agents | `.claude/agents/conductor.md`, `.claude/agents/reviewer.md` |
 | Create/edit rules | `.claude/rules/*.orchestra.md` |
-| Create/edit skills | `.claude/skills/*.orchestra.md` |
+| Create/edit skills | `.claude/skills/*/SKILL.md` |
 | Create/edit blueprints | `.orchestra/blueprints/*.md` |
 | Create/edit commands | `.claude/commands/orchestra/*.md` |
 | Edit knowledge log | `.orchestra/knowledge.md` |

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

@@ -75,11 +75,11 @@ summary: {2-3 sentences}
 ```
 
 **Process:**
-1. If **approved** → proceed, milestone is ready for conductor
+1. If **approved** → proceed, milestone is ready
 2. If **changes-requested** → PM reads issues, fixes milestone files, re-launches reviewer
 3. After max rounds with no blocking issues → proceed with suggestions logged in grooming.md
 4. After max rounds with blocking issues still open → escalate to user, do NOT proceed
-5. Present verdict to user before finalizing
+5. Present verdict to user. When ready, tell them: "You can run `/orchestra:start` in a second terminal to begin execution."
 
 ### milestone.md Format
 
@@ -103,8 +103,8 @@ 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: []   
+skills: []                    # list .claude/skills/, assign relevant ones by name
+depends_on: []
 ---
 
 ## Objective

package/template/CLAUDE.md

@@ -44,7 +44,7 @@ Role IDs: orchestrator, product-manager, architect, backend-engineer, frontend-e
 - Two-terminal model: PM plans in one terminal, conductor executes in another
 - Each role writes only to its ownership scope (defined in role file)
 - Rules (`.claude/rules/*.orchestra.md`) auto-loaded. Skills loaded per phase.
-- **PROTECTED:** Non-Orchestrator roles NEVER modify `.orchestra/roles/`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `.claude/agents/`, `.claude/rules/*.orchestra.md`, `.claude/skills/*.orchestra.md`, `.claude/commands/orchestra/`, `CLAUDE.md`, or `docs/`.
+- **PROTECTED:** Non-Orchestrator roles NEVER modify `.orchestra/roles/`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `.claude/agents/`, `.claude/rules/*.orchestra.md`, `.claude/skills/*/SKILL.md`, `.claude/commands/orchestra/`, `CLAUDE.md`, or `docs/`.
 
 ## Development
 

package/template/agents/conductor.md

@@ -76,7 +76,7 @@ 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)
+2. Read skill files from phase `.claude/skills/{name}/SKILL.md` → 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

package/template/commands/help.md

@@ -40,7 +40,7 @@ CONFIG:
 
 FILES:
   .claude/agents/                  Conductor + Reviewer agents
-  .claude/skills/*.orchestra.md    Domain checklists (auth, CRUD, deploy, etc.)
+  .claude/skills/*/SKILL.md        Domain checklists (auth, CRUD, deploy, etc.)
   .claude/rules/*.orchestra.md     Discipline rules (verification, commit format, etc.)
   .claude/commands/orchestra/      Orchestra commands
   .orchestra/roles/                Role identities (one file per role)

package/template/rules/role-boundaries.orchestra.md

@@ -6,7 +6,7 @@ Before writing ANY file, check your role's ownership scope.
 
 | Role | Can Write | Everything Else |
 |------|-----------|----------------|
-| Orchestrator | `.orchestra/roles/`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `.claude/agents/`, `.claude/rules/*.orchestra.md`, `.claude/skills/*.orchestra.md`, `.claude/commands/orchestra/`, `CLAUDE.md`, `docs/` | Refuse |
+| Orchestrator | `.orchestra/roles/`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `.claude/agents/`, `.claude/rules/*.orchestra.md`, `.claude/skills/*/SKILL.md`, `.claude/commands/orchestra/`, `CLAUDE.md`, `docs/` | Refuse |
 | PM | `.orchestra/milestones/*` (prd, milestone, grooming, phases) | Refuse |
 | Conductor | `.orchestra/milestones/*/context.md`, `.orchestra/knowledge.md` (append) | Refuse |
 | Backend/Frontend/Architect/Adaptive | Only what phase `scope:` defines | Refuse |