@sulhadin/orchestrator 1.1.0 → 1.3.0

package/README.md

@@ -8,11 +8,11 @@ Building a feature with Claude Code typically looks like this:
 
 ```
 You: "Build user authentication"
-You: *opens terminal* "@architect — design the system"
+You: *opens terminal* "#architect — design the system"
 You: *reads RFC, approves*
-You: *opens terminal* "@backend — implement the API"
-You: *opens terminal* "@reviewer — review the code"
-You: *opens terminal* "@pm — close the feature"
+You: *opens terminal* "#backend — implement the API"
+You: *opens terminal* "#reviewer — review the code"
+You: *opens terminal* "#pm — close the feature"
 ```
 
 You become the orchestrator. You carry context between sessions, sequence work in the right order, and manage the pipeline manually. This is tedious and error-prone.
@@ -22,13 +22,13 @@ You become the orchestrator. You carry context between sessions, sequence work i
 Orchestra turns Claude Code's PM role into an autonomous orchestrator. You describe what you want, PM handles the rest:
 
 ```
-You: "@pm"
+You: "#pm"
 You: "I want user authentication with JWT"
 PM:  creates milestone, grooms phases, dispatches worker agent
-     @architect writes RFC → you approve
-     @backend implements phase by phase → each phase = one commit
-     @frontend builds the UI → each phase = one commit
-     @reviewer reviews unpushed commits
+     #architect writes RFC → you approve
+     #backend implements phase by phase → each phase = one commit
+     #frontend builds the UI → each phase = one commit
+     #reviewer reviews unpushed commits
      you approve → PM pushes to origin
      milestone closed.
 ```
@@ -43,11 +43,11 @@ You ←→ PM (always-on orchestrator)
         ├── Creates milestone with groomed phases
         ├── Spawns one worker agent (all roles loaded)
         │
-        ├── SendMessage("@architect: write RFC") → awaits
-        ├── SendMessage("@backend: phase-1")     → awaits → commit
-        ├── SendMessage("@backend: phase-2")     → awaits → commit
-        ├── SendMessage("@frontend: phase-3")    → awaits → commit
-        ├── SendMessage("@reviewer: review")     → awaits
+        ├── SendMessage("#architect: write RFC") → awaits
+        ├── SendMessage("#backend: phase-1")     → awaits → commit
+        ├── SendMessage("#backend: phase-2")     → awaits → commit
+        ├── SendMessage("#frontend: phase-3")    → awaits → commit
+        ├── SendMessage("#reviewer: review")     → awaits
         │
         ├── You approve → PM pushes to origin
         └── Milestone closed
@@ -138,10 +138,10 @@ your-project/
 
 ## Usage
 
-Open Claude Code in your project and say `@pm`:
+Open Claude Code in your project and say `#pm`:
 
 ```
-You: @pm
+You: #pm
 PM:  "No active milestones. Ready for instructions."
 
 You: "I want to add a health check endpoint"
@@ -158,12 +158,12 @@ PM:  *creates milestone, grooms phases, dispatches worker*
 
 | Command | Description |
 |---------|------------|
-| `@pm` | Activate Product Manager |
-| `@backend` | Activate Backend Engineer (manual mode) |
-| `@frontend` | Activate Frontend Engineer (manual mode) |
-| `@reviewer` | Activate Code Reviewer (manual mode) |
-| `@architect` | Activate Architect (manual mode) |
-| `@owner` | Activate Owner (system maintenance) |
+| `#pm` | Activate Product Manager |
+| `#backend` | Activate Backend Engineer (manual mode) |
+| `#frontend` | Activate Frontend Engineer (manual mode) |
+| `#reviewer` | Activate Code Reviewer (manual mode) |
+| `#architect` | Activate Architect (manual mode) |
+| `#owner` | Activate Owner (system maintenance) |
 | `status` | Pipeline status report (PM only) |
 | `orc help` | Show all commands |
 
@@ -172,7 +172,7 @@ PM:  *creates milestone, grooms phases, dispatches worker*
 You can still use roles directly without PM orchestration:
 
 ```
-You: @backend
+You: #backend
 BE:  *checks milestones for pending backend phases*
      *starts working*
 ```

package/bin/index.js

@@ -11,6 +11,66 @@ const ORCHESTRA_SECTION_END = "<!-- /orchestra -->";
 
 const USER_DIRS = ["milestones"];
 
+const ALLOW_PERMISSIONS = [
+  "Bash(npm *)",
+  "Bash(npx *)",
+  "Bash(node *)",
+  "Bash(git *)",
+  "Bash(yarn *)",
+  "Bash(pnpm *)",
+  "Bash(tsc *)",
+  "Bash(npx tsc *)",
+  "Bash(npx vitest *)",
+  "Bash(mkdir *)",
+  "Bash(cat *)",
+  "Bash(ls *)",
+  "Read(*)",
+  "Write(*)",
+  "Edit(*)",
+  "Glob(*)",
+  "Grep(*)",
+  "Agent(*)",
+];
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const flags = {
+    skipPermissions: false,
+    help: false,
+  };
+
+  for (const arg of args) {
+    switch (arg) {
+      case "--dangerously-skip-permissions":
+        flags.skipPermissions = true;
+        break;
+      case "--help":
+      case "-h":
+        flags.help = true;
+        break;
+      default:
+        console.error("  Unknown flag: " + arg);
+        process.exit(1);
+    }
+  }
+
+  return flags;
+}
+
+function showHelp() {
+  console.log("");
+  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("    --help, -h                       Show this help");
+  console.log("");
+  console.log("  Examples:");
+  console.log("    npx @sulhadin/orchestrator");
+  console.log("    npx @sulhadin/orchestrator --dangerously-skip-permissions");
+  console.log("");
+}
+
 function copyDirRecursive(src, dest) {
   if (!fs.existsSync(dest)) {
     fs.mkdirSync(dest, { recursive: true });
@@ -58,7 +118,49 @@ function extractOrchestraSection(content) {
   return content.slice(startIdx, endIdx + ORCHESTRA_SECTION_END.length);
 }
 
+function setupPermissions() {
+  const claudeDir = path.join(targetDir, ".claude");
+  const settingsPath = path.join(claudeDir, "settings.local.json");
+
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+  }
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings.permissions) {
+    settings.permissions = {};
+  }
+
+  const existing = settings.permissions.allow || [];
+  const merged = [...new Set([...existing, ...ALLOW_PERMISSIONS])];
+  settings.permissions.allow = merged;
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+
+  const added = merged.length - existing.length;
+  if (added > 0) {
+    console.log("  [+] Permissions configured (" + added + " rules added to .claude/settings.local.json)");
+  } else {
+    console.log("  [~] Permissions already configured");
+  }
+}
+
 function run() {
+  const flags = parseArgs();
+
+  if (flags.help) {
+    showHelp();
+    return;
+  }
+
   console.log("");
   console.log("  Orchestra — AI Team Orchestration");
   console.log("  Installing into: " + targetDir);
@@ -69,7 +171,6 @@ function run() {
   const isUpgrade = fs.existsSync(orchestraDest);
 
   if (isUpgrade) {
-    // Backup user data directories
     const backups = {};
 
     for (const dir of USER_DIRS) {
@@ -77,7 +178,6 @@ function run() {
       const backupPath = path.join(targetDir, ".orchestra-backup-" + dir);
 
       if (fs.existsSync(dirPath)) {
-        // Check if directory has real content (not just .gitkeep)
         const files = fs.readdirSync(dirPath).filter((f) => f !== ".gitkeep");
         if (files.length > 0) {
           copyDirRecursive(dirPath, backupPath);
@@ -87,19 +187,15 @@ function run() {
       }
     }
 
-    // Remove old .orchestra/
     rmDirRecursive(orchestraDest);
     console.log("  [~] Removed old .orchestra/");
 
-    // Copy fresh .orchestra/
     copyDirRecursive(orchestraSrc, orchestraDest);
     console.log("  [+] .orchestra/ installed (clean)");
 
-    // Restore user data
     for (const [dir, backupPath] of Object.entries(backups)) {
       const restorePath = path.join(orchestraDest, dir);
 
-      // Remove the template's empty dir first
       if (fs.existsSync(restorePath)) {
         rmDirRecursive(restorePath);
       }
@@ -109,7 +205,6 @@ function run() {
       console.log("  [+] Restored " + dir + "/");
     }
   } else {
-    // Fresh install
     copyDirRecursive(orchestraSrc, orchestraDest);
     console.log("  [+] .orchestra/ installed");
   }
@@ -151,12 +246,17 @@ function run() {
     console.log("  [+] CLAUDE.md created");
   }
 
+  // Handle permissions
+  if (flags.skipPermissions) {
+    setupPermissions();
+  }
+
   console.log("");
   console.log("  Done! Orchestra is ready.");
   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. Say "#pm" to start orchestrating');
   console.log("");
 }
 

package/package.json

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

package/template/.orchestra/README.md

@@ -15,10 +15,10 @@ You (User)
       → PM discusses features with you, creates milestones
       → PM creates a worker agent session (all roles loaded)
       → PM dispatches phases sequentially:
-          @architect → writes RFC
-          @backend   → implements backend phases (each → commit)
-          @frontend  → implements frontend phases (each → commit)
-          @reviewer  → reviews unpushed commits
+          #architect → writes RFC
+          #backend   → implements backend phases (each → commit)
+          #frontend  → implements frontend phases (each → commit)
+          #reviewer  → reviews unpushed commits
       → PM pushes to origin after approval
       → PM closes milestone
 ```
@@ -57,7 +57,7 @@ User talks only to PM. PM dispatches a worker agent to execute all roles:
 1. PM creates milestone with groomed phases
 2. PM creates worker agent session (via `Agent` tool — all roles loaded once)
 3. PM dispatches phases via `SendMessage` → awaits result → dispatches next
-4. Worker switches roles as PM instructs (`@architect`, `@backend`, `@frontend`, `@reviewer`)
+4. Worker switches roles as PM instructs (`#architect`, `#backend`, `#frontend`, `#reviewer`)
 5. Each phase → one commit. Milestone done → push to origin.
 
 ### Manual Mode
@@ -65,8 +65,8 @@ User talks only to PM. PM dispatches a worker agent to execute all roles:
 User switches roles directly — same as before:
 
 ```
-User → @backend (implement)
-User → @reviewer (review)
+User → #backend (implement)
+User → #reviewer (review)
 ```
 
 Roles check `.orchestra/milestones/` for phases assigned to them. Manual mode
@@ -77,8 +77,10 @@ works alongside autonomous mode — user can mix both.
 ## Milestone Lifecycle
 
 ```
-PM creates milestone (status: planning)
-  → PM grooms phases (detailed scope, objectives)
+PM discusses feature with user
+  → PM plans scope, phases, acceptance criteria
+  → [USER APPROVAL GATE: Milestone creation]
+  → PM creates milestone (status: planning)
   → PM dispatches architect for RFC (if needed)
   → [USER APPROVAL GATE: RFC → Implementation]
   → PM dispatches backend phases (sequential, each → commit)
@@ -158,6 +160,7 @@ Rules:
 ## Approval Gates
 
 The user must approve before these transitions:
+- **Milestone creation** — PM discusses and plans, but must get user approval before creating the milestone directory and files
 - **RFC → Implementation** — user reviews architect's RFC
 - **Push to origin** — user approves the final changeset
 
@@ -170,7 +173,7 @@ All other transitions are automatic.
 Reviewer no longer needs task files. Review is based on **unpushed commits**.
 
 ```
-PM dispatches @reviewer via worker agent
+PM dispatches #reviewer via worker agent
   → Reviewer runs: git log origin/{branch}..HEAD
   → Reviewer runs: git diff origin/{branch}...HEAD
   → Reviewer applies full checklist (backend or frontend mode)
@@ -252,7 +255,7 @@ Each role has exclusive write access to specific directories:
 PM dispatches tasks by specifying the role and the work:
 
 ```
-"@backend: Implement phase-1 of M1-user-auth.
+"#backend: Implement phase-1 of M1-user-auth.
 Read: .orchestra/milestones/M1-user-auth/phases/phase-1.md"
 ```
 
@@ -289,28 +292,28 @@ sequenceDiagram
     PM->>PM: Create milestone + groom phases
     PM->>W: Agent(worker.md) — create session
 
-    PM->>W: SendMessage(@architect: write RFC)
+    PM->>W: SendMessage(#architect: write RFC)
     W-->>PM: RFC result
     PM->>U: RFC ready — approve?
     U->>PM: Approved
 
     loop Each backend phase
-        PM->>W: SendMessage(@backend: phase-N)
+        PM->>W: SendMessage(#backend: phase-N)
         W-->>PM: Phase result + commit
         PM->>U: Progress: phase-N done
     end
 
     loop Each frontend phase
-        PM->>W: SendMessage(@frontend: phase-N)
+        PM->>W: SendMessage(#frontend: phase-N)
         W-->>PM: Phase result + commit
         PM->>U: Progress: phase-N done
     end
 
-    PM->>W: SendMessage(@reviewer: review)
+    PM->>W: SendMessage(#reviewer: review)
     W-->>PM: Review verdict
 
     alt Changes requested
-        PM->>W: SendMessage(@backend/@frontend: fix)
+        PM->>W: SendMessage(#backend/#frontend: fix)
         W-->>PM: Fix result + commit
     end
 
@@ -326,15 +329,15 @@ sequenceDiagram
     participant PM as Product Manager
     participant W as Worker Agent
 
-    PM->>W: "@backend: implement phase-1"
+    PM->>W: "#backend: implement phase-1"
     Note over W: Read phase file<br/>Activate backend role<br/>Implement + test<br/>Commit
     W-->>PM: Result: done, committed abc123
 
-    PM->>W: "@backend: implement phase-2"
+    PM->>W: "#backend: implement phase-2"
     Note over W: Same session<br/>Full context preserved<br/>Implement + test<br/>Commit
     W-->>PM: Result: done, committed def456
 
-    PM->>W: "@frontend: implement phase-3"
+    PM->>W: "#frontend: implement phase-3"
     Note over W: Role switch<br/>Architect + backend context available<br/>Implement + test<br/>Commit
     W-->>PM: Result: done, committed ghi789
 ```
@@ -347,7 +350,7 @@ sequenceDiagram
     participant W as Worker Agent
     actor U as User
 
-    PM->>W: "@reviewer: review M1-user-auth"
+    PM->>W: "#reviewer: review M1-user-auth"
     Note over W: git log origin/branch..HEAD<br/>git diff origin/branch...HEAD<br/>Apply review checklist
 
     alt Approved
@@ -357,7 +360,7 @@ sequenceDiagram
         PM->>PM: git push + close milestone
     else Changes Requested
         W-->>PM: verdict: changes-requested + issues
-        PM->>W: "@backend: fix issues in phase-2"
+        PM->>W: "#backend: fix issues in phase-2"
         W-->>PM: Fixed + committed
         PM->>U: Fixes applied. Push?
         U->>PM: Yes

package/template/.orchestra/agents/worker.md

@@ -28,7 +28,7 @@ After reading, confirm to PM: "Worker ready. All roles loaded."
 
 ## Role Switching
 
-When PM says `@architect`, `@backend`, `@frontend`, or `@reviewer`:
+When PM says `#architect`, `#backend`, `#frontend`, or `#reviewer`:
 - Switch to that role immediately
 - Follow ONLY that role's ownership scope — do NOT write files outside scope
 - Apply that role's engineering principles and standards
@@ -40,10 +40,10 @@ You can only write to files owned by the **currently active** role:
 
 | Active Role | Can Write |
 |------------|-----------|
-| `@architect` | `.orchestra/milestones/*/rfc.md`, `.orchestra/milestones/*/architecture.md`, `.orchestra/milestones/*/adrs/*`, project configs |
-| `@backend` | `src/*`, `tests/*`, `migrations/*`, `package.json`, `tsconfig.json` |
-| `@frontend` | `frontend/*`, `.orchestra/milestones/*/design.md` |
-| `@reviewer` | Review findings only — never modify source code |
+| `#architect` | `.orchestra/milestones/*/rfc.md`, `.orchestra/milestones/*/architecture.md`, `.orchestra/milestones/*/adrs/*`, project configs |
+| `#backend` | `src/*`, `tests/*`, `migrations/*`, `package.json`, `tsconfig.json` |
+| `#frontend` | `frontend/*`, `.orchestra/milestones/*/design.md` |
+| `#reviewer` | Review findings only — never modify source code |
 
 If you need to write outside your active role's scope, **do not do it**. Report
 the need to PM in your result and PM will dispatch the appropriate role.
@@ -73,7 +73,7 @@ After completing a phase's work:
 
 ## Reviewer Mode
 
-When activated as `@reviewer`, you review **unpushed commits** on the current branch:
+When activated as `#reviewer`, you review **unpushed commits** on the current branch:
 
 ```bash
 git log origin/{current-branch}..HEAD --oneline    # see commits to review
@@ -87,7 +87,7 @@ git diff origin/{current-branch}...HEAD            # see full changeset
 
 ## Architect Mode
 
-When activated as `@architect`:
+When activated as `#architect`:
 - Write RFC to the milestone's `rfc.md` file
 - Write ADRs to the milestone's `adrs/` directory if needed
 - Follow the architect role's technical RFC format

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

@@ -244,7 +244,12 @@ WHAT the user needs without ambiguity. HOW to build it is their decision.
 
 ### Creating a Milestone
 
-When a feature is ready to be built, create a milestone directory:
+**You MUST get user approval before creating a milestone.** After discussing the
+feature, present your plan (scope, phases, acceptance criteria) and explicitly
+ask: "Shall I create the milestone?" Only create the directory and files after
+the user approves.
+
+When approved, create a milestone directory:
 
 ```
 .orchestra/milestones/M{number}-{slug}/
@@ -385,7 +390,7 @@ Send a message to the worker agent specifying the role and phase:
 
 ```
 SendMessage to worker:
-"@backend: Implement phase-1 of M1-user-auth.
+"#backend: Implement phase-1 of M1-user-auth.
 Read the phase file: .orchestra/milestones/M1-user-auth/phases/phase-1.md
 Follow backend-engineer role rules. Commit when done."
 ```
@@ -422,7 +427,7 @@ Reviewer reviews all unpushed commits on the current branch:
 
 ```
 SendMessage to worker:
-"@reviewer: Review milestone M1-user-auth.
+"#reviewer: Review milestone M1-user-auth.
 Check unpushed commits: git log origin/{branch}..HEAD
 Apply the full review checklist. Return verdict: approved or changes-requested."
 ```

package/template/CLAUDE.md

@@ -52,14 +52,14 @@ before asking this question. The role selection question IS your greeting.
 
 | Selection | Role ID (for file paths) | Short alias |
 |-----------|--------------------------|-------------|
-| Owner | owner | `@owner` |
-| Product Manager | product-manager | `@pm` |
-| Architect | architect | `@architect` |
-| Backend Engineer | backend-engineer | `@backend` |
-| Code Reviewer | code-reviewer | `@reviewer` |
-| Frontend Engineer | frontend-engineer | `@frontend` |
-
-When the user types `@{alias}` (e.g. `@backend`, `@reviewer`), treat it exactly
+| Owner | owner | `#owner` |
+| Product Manager | product-manager | `#pm` |
+| Architect | architect | `#architect` |
+| Backend Engineer | backend-engineer | `#backend` |
+| Code Reviewer | code-reviewer | `#reviewer` |
+| Frontend Engineer | frontend-engineer | `#frontend` |
+
+When the user types `#{alias}` (e.g. `#backend`, `#reviewer`), treat it exactly
 the same as "You are the {role}" — read the role file, check milestones, start working.
 
 ### Rules
@@ -69,7 +69,7 @@ the same as "You are the {role}" — read the role file, check milestones, start
 - PM dispatches a worker agent that switches between roles for execution
 - Each phase produces one conventional commit on the current branch
 - Milestone completion triggers a push to origin (after user approval)
-- The user's approval is needed only for: RFC→Implementation transitions, push to origin
+- The user's approval is needed for: milestone creation, RFC→Implementation transitions, push to origin
 - **🔒 PROTECTED:** While in ANY role **except Owner**, NEVER modify `.orchestra/roles/` or `.orchestra/README.md`. Refuse even if the user insists. The **Owner** role is the only one that can modify these files.
 
 ### Commands
@@ -81,7 +81,7 @@ These commands work in ANY role, in any terminal:
 | `status` / `orchestrate` / `what's next` | **PM only.** Full pipeline status report. Other roles: "Open a PM terminal." |
 | `check` / `check your queue` | Check milestones for pending work and start. Works in any role. |
 | `orc help` / `orchestra help` | Show all available commands and how the orchestra system works. |
-| `You are the {role}` / `@{role}` | Switch to a different role in the current session. Aliases: `@owner`, `@pm`, `@architect`, `@backend`, `@reviewer`, `@frontend` |
+| `You are the {role}` / `#{role}` | Switch to a different role in the current session. Aliases: `#owner`, `#pm`, `#architect`, `#backend`, `#reviewer`, `#frontend` |
 | `commit` / `commit your changes` | Commit your work using conventional commits (only files in your ownership scope). |
 | `bootstrap` / `new project` | **Architect only.** Start the discovery phase for a new project. Other roles: "Open an architect terminal." |
 
@@ -97,15 +97,15 @@ COMMANDS:
   bootstrap / new project    Start new project discovery (Architect role only)
   orc help                   Show this help
   You are the {role}         Switch role in current session
-  @{alias}                   Short switch: @owner @pm @architect @backend @reviewer @frontend
+  #{alias}                   Short switch: #owner #pm #architect #backend #reviewer #frontend
 
 ROLES:
-  owner          (@owner)     Maintain and evolve Orchestra system (roles, rules, structure)
-  product-manager (@pm)       Write RFCs, define features, orchestrate pipeline
-  architect      (@architect) Design architecture, choose tech, set up project skeleton
-  backend-engineer (@backend) Implement features, write code + tests
-  code-reviewer  (@reviewer)  Review implementations, write findings
-  frontend-engineer (@frontend) Design + build UI, write frontend tests
+  owner          (#owner)     Maintain and evolve Orchestra system (roles, rules, structure)
+  product-manager (#pm)       Write RFCs, define features, orchestrate pipeline
+  architect      (#architect) Design architecture, choose tech, set up project skeleton
+  backend-engineer (#backend) Implement features, write code + tests
+  code-reviewer  (#reviewer)  Review implementations, write findings
+  frontend-engineer (#frontend) Design + build UI, write frontend tests
 
 PIPELINES:
   New project:    PM → Architect → Engineers start building