claude-orchestration 1.0.4 → 1.0.6

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.6",
   "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,52 @@
-# Orchestration
-
-## Technology Detection
-
-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
-
-If React indicators are present → use `workflows/react/` directory
-
-## Available Workflows
-
-| 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 |
-
-**Workflow Path:**
-- React projects: `workflows/react/{workflow}.md`
-- Other projects: `workflows/{workflow}.md`
-
-## 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
-
+# Orchestration Protocol
+
+**MANDATORY: Process BEFORE any tool usage.**
+
+## 1. CLASSIFY TASK
+
+| 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` |
+
+**Complexity:** 1-2 ops = simple | 3+ ops = complex (add `todo.md`)
+**Technology:** React (`.jsx`/`.tsx`, hooks) → `workflows/react/` | Other → `workflows/`
+
+### Selection
+- **Clear match:** Proceed to binding
+- **Ambiguous:** Use `AskUserQuestion` (header: "Workflow", options: relevant workflows)
+- **No match:** Ask user to clarify
+
+## 2. BINDING (required before ANY tool use)
+
+```
+ORCHESTRATION_BINDING:
+- Task: [description]
+- Workflow: [path]
+- Complexity: [simple/complex]
+```
+
+## 3. EXEMPT TASKS
+
+Requires ALL: single file, 1-2 ops, zero architecture impact, obvious correctness.
+
+```
+ORCHESTRATION_BINDING:
+- Task: [description]
+- Classification: EXEMPT
+```
+
+## 4. COMPLETION
+
+```
+ORCHESTRATION_COMPLETE:
+- Task: [description]
+- Workflow: [used]
+- Files: [modified]
+```

package/templates/claude/workflows/react/bugfix.md

@@ -1,50 +1,32 @@
 # React Bugfix Workflow
 
-> Architecture rules: See orchestration.md. Violations block merge.
+## 1. Reproduce
 
-## Before Coding
+- Confirm bug exists | find minimal repro
+- Check Strict Mode behavior
+- Answer: Expected vs actual? React 18 concurrent issue?
 
-MUST answer:
-- Can I reproduce the bug?
-- What is expected vs actual behavior?
-- Is this related to React 18 concurrent features?
+## 2. Locate Root Cause
 
-## Process
+| Common React 18 Issues |
+|------------------------|
+| Effects missing cleanup |
+| Stale closures in effects |
+| Concurrent rendering race conditions |
+| Automatic batching changes |
 
-### 1. Reproduce and Isolate
-- Confirm the bug exists
-- Check if it only occurs in Strict Mode
-- Find minimal reproduction case
+## 3. Fix
 
-### 2. Locate Root Cause
+- Keep changes within affected feature folder
+- Add cleanup: `return () => controller.abort()`
+- Fix stale closures with proper deps
 
-**Common React 18 issues:**
-- Effects missing cleanup functions
-- Effects with stale closures
-- Race conditions from concurrent rendering
-- Automatic batching behavior changes
+## 4. Verify
 
-### 3. Fix
-
-MUST keep changes within affected feature folder.
-
-```tsx
-// Example: Add cleanup for effects
-useEffect(() => {
-  const controller = new AbortController()
-  fetchData(controller.signal)
-  return () => controller.abort()
-}, [])
-```
-
-### 4. Verify
-- Confirm bug is fixed
-- Test with Strict Mode enabled
-- Add test that would have caught this bug
+- Confirm fix | test with Strict Mode
+- Add regression test
 
 ## Constraints
 
-- A bugfix is NOT an opportunity to refactor
-- The best fix is the smallest fix
-- NEVER introduce barrel exports
-- Note other issues separately—don't fix them here
+- Smallest fix only | NO refactoring
+- NO barrel exports | note other issues separately

package/templates/claude/workflows/react/feature.md

@@ -1,55 +1,37 @@
 # React Feature Workflow
 
-> Architecture rules: See orchestration.md. Violations block merge.
+## 1. Architecture
 
-## Before Coding
+**IF not specified:** Use `AskUserQuestion` (header: "Architecture")
 
-MUST answer:
-- What problem does this feature solve?
-- What's the minimal viable version?
-- Which feature folder does this belong in?
-- Are there existing patterns to follow?
+| Architecture | Structure |
+|--------------|-----------|
+| Feature-driven | `features/{name}/components\|hooks\|utils/` |
+| Flat feature-driven | `features/{name}/` flat files |
+| Atomic design | `atoms\|molecules\|organisms\|templates/` |
 
-## Process
+**IF project has patterns:** Follow existing, skip question.
 
-### 1. Understand Context
-- Read related existing code
-- Identify the target feature folder
-- Check for similar implementations
-- Review reusable hooks and utilities
+## 2. Context
 
-### 2. Plan Implementation
-- Break into small, testable pieces
-- Plan component hierarchy
-- Identify shared vs feature-specific code
-- Design state approach (local, context, or external)
+- Read related code, identify target folder
+- Check similar implementations, reusable hooks/utils
+- Answer: What problem? Minimal version? Which folder?
 
-### 3. Implement
+## 3. Implement
 
-**Components:**
-- Function components only
-- `useState`/`useReducer` for local state
+**Components:** Function only | `useState`/`useReducer` for local state
+**Hooks:** Extract logic | `hooks/{feature}/{name}.ts` | descriptive names
+**State:** Lift only as needed | composition over prop drilling
 
-**Hooks:**
-- Extract reusable logic into custom hooks
-- Components handle rendering; hooks handle logic
-- Name descriptively: `useAuthState`, `useFormValidation`
-- Place in `hooks/{feature}/{hookName}.ts`
+## 4. Validate
 
-**State:**
-- Lift state only as high as necessary
-- Prefer composition over prop drilling
-- `useSyncExternalStore` for external state
-
-### 4. Validate
-- Run existing tests for regressions
-- Add tests for new components/hooks
-- Test loading and error states
-- Remove debugging code and unused imports
+- Run tests for regressions
+- Add tests for new code
+- Test loading/error states
+- Remove debug code
 
 ## Constraints
 
-- NEVER create `index.ts` or `index.tsx` files
-- MUST import directly from file, not folder
-- MUST match surrounding code style
-- NEVER add features beyond what was requested
+- NO `index.ts`/`index.tsx` | import from file directly
+- Match existing style | no extra features

package/templates/claude/workflows/react/pr.md

@@ -2,23 +2,18 @@
 
 ## Process
 
-1. Read the diff between current branch and main/master
-2. Analyze changes to understand what was done
-3. Output a PR title and description
+1. Read diff (current branch vs main/master)
+2. Analyze changes
+3. Output title + description
 
-## Output Format
+## Output
 
 ```
-PR Title: <concise title>
-
-Description:
-<2-3 sentences: what changed and why>
+PR Title: <imperative mood>
+Description: <2-3 sentences: what + why>
 ```
 
 ## Constraints
 
-- MUST use imperative mood ("Add feature" not "Added feature")
-- MUST mention breaking changes if any
-- Keep description focused on "what" and "why"
-- NEVER create branches, push, or create PRs remotely
-- ONLY output the title and description for the user to copy
+- Imperative mood ("Add" not "Added") | mention breaking changes
+- Output only | NO branch/push/remote PR creation

package/templates/claude/workflows/react/refactor.md

@@ -1,43 +1,32 @@
 # React Refactor Workflow
 
-> Architecture rules: See orchestration.md. Violations block merge.
+## 1. Safety Net
 
-## Before Coding
+- Run tests | add if coverage insufficient
+- Answer: What improvement? How verify unchanged behavior?
 
-MUST answer:
-- What specific improvement am I making?
-- Is there adequate test coverage?
-- How will I verify behavior is unchanged?
+## 2. Plan
 
-## Process
-
-### 1. Ensure Safety Net
-- Run tests to confirm they pass
-- Add tests if coverage is insufficient
-
-### 2. Plan
-- Map all imports and dependencies
-- Identify all callers of affected code
+- Map imports/dependencies | identify all callers
 - Break into small, safe steps
 
-### 3. Execute Incrementally
+## 3. Execute
 
-Make one type of change at a time. Examples:
+One change type at a time | run tests after each:
 
-- Rename files to match folder names
-- Convert barrel imports to direct imports
-- Extract logic into hooks
-- Split large components
+| Change Types |
+|--------------|
+| Rename files to match folders |
+| Barrel → direct imports |
+| Extract logic into hooks |
+| Split large components |
 
-Run tests after each step.
+## 4. Validate
 
-### 4. Validate
-- All tests pass
-- No `index.ts` or `index.tsx` files remain
-- All entry points match folder names
+- All tests pass | no `index.ts`/`index.tsx`
+- Entry points match folder names
 
 ## Constraints
 
-- Refactoring changes structure, NOT behavior
-- NEVER fix bugs during refactor—note them separately
-- MUST keep scope contained: one change type at a time
+- Structure only, NOT behavior | NO bug fixes
+- One change type at a time | note issues separately

package/templates/claude/workflows/react/review.md

@@ -1,54 +1,46 @@
 # React Code Review Workflow
 
-> Architecture rules: See orchestration.md. Violations block merge.
+## 1. Understand
 
-## Before Reviewing
+- Read PR description | review diff scope
+- Answer: What is the goal? What files changed?
 
-MUST answer:
-- What is this change trying to accomplish?
-- What files are modified?
+## 2. Architecture Checklist
 
-## Process
+| Check | Rule |
+|-------|------|
+| Barrels | No `index.ts`/`index.tsx` |
+| Entry files | Match folder names (`Button/Button.tsx`) |
+| Imports | Direct, not barrel |
+| Colocation | Component + hooks + types + tests together |
+| Placement | Correct feature folder |
 
-### 1. Understand the Change
-- Read the PR description
-- Review the diff to understand scope
-- Check if the approach makes sense for the goal
+## 3. React Patterns Checklist
 
-### 2. Check Architecture Compliance
+| Check | Rule |
+|-------|------|
+| Components | Function only, no class |
+| Hooks | No conditionals, proper deps |
+| Effects | Cleanup where needed |
+| Memory | No leaks (subscriptions, timers) |
+| States | Loading + error handled |
 
-- [ ] No `index.ts` or `index.tsx` barrel files
-- [ ] Entry files match folder names (`Button/Button.tsx`)
-- [ ] Direct imports used, not barrel imports
-- [ ] Files colocated properly (component, hooks, types, tests together)
-- [ ] New code placed in correct feature folder
+## 4. Code Quality Checklist
 
-### 3. Check React Patterns
+| Check | Rule |
+|-------|------|
+| Debug | No console.log/debugger |
+| Imports | No unused |
+| Types | No unjustified `any` |
+| Tests | Cover new functionality |
+| Scope | No unrelated changes |
 
-- [ ] Function components only (no class components)
-- [ ] Hooks follow rules (no conditional hooks, proper dependencies)
-- [ ] Effects have cleanup where needed
-- [ ] No obvious memory leaks (subscriptions, timers)
-- [ ] Loading and error states handled
+## 5. Feedback
 
-### 4. Check Code Quality
-
-- [ ] No debugging code left in (console.log, debugger)
-- [ ] No unused imports or variables
-- [ ] Types are accurate (no `any` without justification)
-- [ ] Tests cover new functionality
-- [ ] No unrelated changes mixed in
-
-### 5. Provide Feedback
-
-Categorize comments:
-- **Blocking**: Must fix before merge (bugs, architecture violations)
-- **Suggestion**: Improvements to consider
-- **Question**: Clarification needed
+- **Blocking:** Must fix (bugs, architecture violations)
+- **Suggestion:** Improvements | **Question:** Clarification
 
 ## Constraints
 
-- NEVER approve code with architecture violations
-- NEVER approve code without understanding what it does
-- Keep feedback specific and actionable
-- Suggest fixes, not just problems
+- NO approval with violations | must understand code
+- Specific + actionable | suggest fixes, not just problems