claude-orchestration 1.0.4 → 1.0.5

package/bin/cli.js

@@ -3,39 +3,18 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { checkbox, confirm } from "@inquirer/prompts";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-if (process.argv.includes("--help") || process.argv.includes("-h")) {
-  console.log(`
-Usage: npx claude-orchestration
-
-Scaffolds Claude orchestration workflows into your project.
-
-Creates a .claude/ directory with workflow templates for:
-  - feature.md   Building new functionality
-  - bugfix.md    Diagnosing and fixing bugs
-  - refactor.md  Improving code structure
-  - pr.md        Creating pull requests
-  - docs.md      Writing documentation
-
-Options:
-  -h, --help     Show this help message
-  -v, --version  Show version number
-`);
-  process.exit(0);
-}
-
-if (process.argv.includes("--version") || process.argv.includes("-v")) {
-  const pkg = JSON.parse(
-    await fs.readFile(path.join(__dirname, "..", "package.json"), "utf-8")
-  );
-  console.log(pkg.version);
-  process.exit(0);
-}
+const pkg = JSON.parse(
+  await fs.readFile(path.join(__dirname, "..", "package.json"), "utf-8")
+);
 
 const SOURCE_DIR = path.join(__dirname, "..", "templates", "claude");
+const WORKFLOWS_DIR = path.join(SOURCE_DIR, "workflows");
 const DEST_NAME = ".claude";
 
 const ORCHESTRATION_INSTRUCTION = `
@@ -45,6 +24,38 @@ const ORCHESTRATION_INSTRUCTION = `
 For complex tasks, refer to .claude/orchestration.md for available workflows.
 `;
 
+const ROOT_WORKFLOWS = [
+  {
+    name: "todo.md",
+    description: "Multi-step task management (uses 15-20% more tokens)",
+    checked: false,
+  },
+];
+
+async function getWorkflowFolders() {
+  const entries = await fs.readdir(WORKFLOWS_DIR, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+}
+
+async function getWorkflowFiles(folder) {
+  const folderPath = path.join(WORKFLOWS_DIR, folder);
+  const entries = await fs.readdir(folderPath, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => entry.name);
+}
+
+function formatFolderName(folder) {
+  return folder.charAt(0).toUpperCase() + folder.slice(1);
+}
+
+function formatWorkflowName(filename) {
+  const name = filename.replace(".md", "");
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
 async function findClaudeMdFiles(projectDir) {
   const entries = await fs.readdir(projectDir, { withFileTypes: true });
   return entries
@@ -76,30 +87,136 @@ async function updateClaudeMd(projectDir) {
   }
 }
 
-async function copyDir(src, dest) {
-  await fs.mkdir(dest, { recursive: true });
-  const entries = await fs.readdir(src, { withFileTypes: true });
+async function copyFile(src, dest) {
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  await fs.copyFile(src, dest);
+  console.log(`  Created: ${path.relative(process.cwd(), dest)}`);
+}
+
+async function runInteractiveSetup() {
+  console.log("Claude Orchestration Setup\n");
+
+  const folders = await getWorkflowFolders();
+  const selectedFiles = [];
+
+  // Step 1: Select workflow folders
+  const selectedFolders = await checkbox({
+    message: "Select workflow categories:",
+    choices: folders.map((folder) => ({
+      name: formatFolderName(folder),
+      value: folder,
+      checked: true,
+    })),
+  });
+
+  // Step 2: For each selected folder, select individual workflows
+  for (const folder of selectedFolders) {
+    const files = await getWorkflowFiles(folder);
+
+    const selectedWorkflows = await checkbox({
+      message: `Select ${formatFolderName(folder)} workflows:`,
+      choices: files.map((file) => ({
+        name: formatWorkflowName(file),
+        value: file,
+        checked: true,
+      })),
+    });
+
+    for (const file of selectedWorkflows) {
+      selectedFiles.push({ folder, file });
+    }
+  }
+
+  // Step 3: Select root-level workflows (like todo.md)
+  if (ROOT_WORKFLOWS.length > 0) {
+    const selectedRootWorkflows = await checkbox({
+      message: "Select additional workflows:",
+      choices: ROOT_WORKFLOWS.map((w) => ({
+        name: `${w.name} - ${w.description}`,
+        value: w.name,
+        checked: w.checked,
+      })),
+    });
+
+    for (const file of selectedRootWorkflows) {
+      selectedFiles.push({ folder: null, file });
+    }
+  }
+
+  if (selectedFiles.length === 0) {
+    const continueWithOrchestration = await confirm({
+      message: "No workflows selected. Install only the orchestration guide?",
+      default: true,
+    });
+
+    if (!continueWithOrchestration) {
+      console.log("Setup cancelled.");
+      process.exit(0);
+    }
+  }
+
+  return selectedFiles;
+}
+
+async function getAllWorkflows() {
+  const folders = await getWorkflowFolders();
+  const allFiles = [];
+
+  for (const folder of folders) {
+    const files = await getWorkflowFiles(folder);
+    for (const file of files) {
+      allFiles.push({ folder, file });
+    }
+  }
 
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
+  for (const w of ROOT_WORKFLOWS) {
+    allFiles.push({ folder: null, file: w.name });
+  }
+
+  return allFiles;
+}
 
-    if (entry.isDirectory()) {
-      await copyDir(srcPath, destPath);
+async function copySelectedWorkflows(selectedFiles, targetDir) {
+  const workflowsDir = path.join(targetDir, "workflows");
+
+  for (const { folder, file } of selectedFiles) {
+    if (folder) {
+      const src = path.join(WORKFLOWS_DIR, folder, file);
+      const dest = path.join(workflowsDir, folder, file);
+      await copyFile(src, dest);
     } else {
-      await fs.copyFile(srcPath, destPath);
-      console.log(`  Created: ${path.relative(process.cwd(), destPath)}`);
+      const src = path.join(WORKFLOWS_DIR, file);
+      const dest = path.join(workflowsDir, file);
+      await copyFile(src, dest);
     }
   }
 }
 
-async function main() {
+async function main(options) {
   const targetDir = path.join(process.cwd(), DEST_NAME);
 
-  console.log("Claude Orchestration Setup\n");
-
   try {
-    await copyDir(SOURCE_DIR, targetDir);
+    let selectedFiles;
+
+    if (options.all) {
+      selectedFiles = await getAllWorkflows();
+      console.log("Claude Orchestration Setup\n");
+      console.log("Installing all workflows...\n");
+    } else {
+      selectedFiles = await runInteractiveSetup();
+      console.log();
+    }
+
+    await fs.mkdir(targetDir, { recursive: true });
+
+    const orchestrationSrc = path.join(SOURCE_DIR, "orchestration.md");
+    const orchestrationDest = path.join(targetDir, "orchestration.md");
+    await copyFile(orchestrationSrc, orchestrationDest);
+
+    if (selectedFiles.length > 0) {
+      await copySelectedWorkflows(selectedFiles, targetDir);
+    }
+
     await updateClaudeMd(process.cwd());
     console.log("\nDone! Orchestration files have been added to .claude/");
   } catch (error) {
@@ -108,4 +225,13 @@ async function main() {
   }
 }
 
-main();
+const program = new Command();
+
+program
+  .name("claude-orchestration")
+  .description("Scaffolds Claude orchestration workflows into your project")
+  .version(pkg.version)
+  .option("-a, --all", "Install all workflows without prompting")
+  .action((options) => main(options));
+
+program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-orchestration",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "CLI tool to scaffold Claude orchestration workflows into your project",
   "bin": {
     "claude-orchestration": "bin/cli.js"
@@ -26,5 +26,9 @@
   ],
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "@inquirer/prompts": "^7.0.0"
   }
 }

package/templates/claude/orchestration.md

@@ -1,41 +1,101 @@
-# Orchestration
+# Orchestration Protocol
 
-## Technology Detection
+**MANDATORY: Process this file BEFORE any tool usage.**
 
-Before selecting a workflow, determine the technology stack:
+---
 
-**React Project Indicators:**
-- Files with `.jsx` or `.tsx` extensions
-- Imports from `react`, `react-dom`, or `@react-*` packages
-- React hooks (`useState`, `useEffect`, `useContext`, etc.)
-- JSX syntax (`<Component />`, `<div className=...>`)
-- `package.json` with `react` as a dependency
-- Frameworks: Next.js, Remix, Gatsby, Create React App
+## 1. CLASSIFY TASK
 
-If React indicators are present → use `workflows/react/` directory
+### ⛔ STOP CHECKPOINT #1
 
-## Available Workflows
+| Signal Words | Workflow |
+|--------------|----------|
+| build, create, add, implement, new | `feature.md` |
+| fix, broken, error, crash, bug | `bugfix.md` |
+| clean up, improve, restructure, rename | `refactor.md` |
+| slow, optimize, performance, speed | `performance.md` |
+| review, check, PR, merge | `review.md` |
+| PR description, pull request title | `pr.md` |
+| document, README, explain | `docs.md` |
+| complex, multi-step, plan | `todo.md` |
 
-| Workflow | Use When |
-|----------|----------|
-| `feature.md` | Building new functionality |
-| `bugfix.md` | Diagnosing and fixing bugs |
-| `refactor.md` | Improving code without behavior changes |
-| `performance.md` | Profiling and optimizing performance |
-| `review.md` | Reviewing code for merge |
-| `pr.md` | Generating PR title and description |
-| `docs.md` | Writing or updating documentation |
-| `todo.md` | Creating and managing TODO lists for complex tasks |
+**Complexity:** 1-2 ops (simple) | 3+ ops (complex → also use `todo.md`)
 
-**Workflow Path:**
-- React projects: `workflows/react/{workflow}.md`
-- Other projects: `workflows/{workflow}.md`
+**Technology:** React (`.jsx`/`.tsx`, react imports, hooks) → `workflows/react/` | Other → `workflows/`
 
-## Rules
+---
 
-- Use judgment to select **at most one** workflow per task
-- Skip workflows for trivial tasks (typos, simple renames, one-line fixes)
-- Workflows are process guidance, not rigid scripts
-- Read the workflow file before starting, adapt steps as needed
-- Use `todo.md` workflow for any task requiring 3+ distinct steps
+## 2. DECLARE BINDING
 
+### ⛔ STOP CHECKPOINT #2
+
+Before ANY tool use, declare:
+
+```
+ORCHESTRATION_BINDING:
+- Task: [description]
+- Classification: [workflow]
+- Workflow: [path]
+- Complexity: [1-2 ops / 3+ ops]
+- Technology: [React / Other / N/A]
+```
+
+---
+
+## 3. EXEMPT TASKS
+
+Exemption requires ALL: single file, 1-2 ops, zero architectural impact, obvious correctness, no debugging.
+
+**NOT exempt:** "quick bug fix" (needs investigation), "small feature" (needs context), "make it faster" (needs measurement).
+
+Exempt binding:
+```
+ORCHESTRATION_BINDING:
+- Task: [description]
+- Classification: EXEMPT
+- Justification: [criteria met]
+```
+
+---
+
+## 4. VIOLATIONS
+
+| Type | Indicator |
+|------|-----------|
+| Missing Binding | Tool use without declaration |
+| Premature Tool Use | Edit before workflow read |
+| Scope Creep | Unplanned files modified |
+| False Exemption | Exempt claim for complex task |
+
+**Self-correct:** STOP → DECLARE violation → RETURN to checkpoint → REBIND → CONTINUE
+
+---
+
+## 5. EXECUTION
+
+**Pre-Work:** Binding declared, workflow read, "Before Coding" answered
+
+**Mid-Work:** Within scope, no unplanned files, todo tracking if 3+ ops
+
+**Completion:** Validation done, then declare:
+```
+ORCHESTRATION_COMPLETE:
+- Task: [description]
+- Workflow: [used]
+- Files: [modified]
+```
+
+---
+
+## 6. WORKFLOW REFERENCE
+
+| Workflow | React | Other |
+|----------|-------|-------|
+| feature | `workflows/react/feature.md` | `workflows/feature.md` |
+| bugfix | `workflows/react/bugfix.md` | `workflows/bugfix.md` |
+| refactor | `workflows/react/refactor.md` | `workflows/refactor.md` |
+| performance | `workflows/react/performance.md` | `workflows/performance.md` |
+| review | `workflows/react/review.md` | `workflows/review.md` |
+| pr | `workflows/react/pr.md` | `workflows/pr.md` |
+| docs | `workflows/react/docs.md` | `workflows/docs.md` |
+| todo | `workflows/react/todo.md` | `workflows/todo.md` |