agentic-orchestration 1.0.7

package/README.md

@@ -0,0 +1,48 @@
+# agentic-orchestration
+
+CLI tool to scaffold agent orchestration workflows into your project.
+
+## Usage
+
+```bash
+npx agentic-orchestration
+```
+
+This will create a `.orchestration/` directory with workflow templates:
+
+```
+.orchestration/
+  orchestration.md
+  workflows/
+    react/
+      feature.md
+      bugfix.md
+      refactor.md
+      performance.md
+      review.md
+      pr.md
+      docs.md
+```
+
+## What it does
+
+1. Copies workflow templates to `.orchestration/` in your project
+2. Appends orchestration reference to your `ORCHESTRATION.md` (if it exists)
+
+## 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 documentation |
+
+The tool auto-detects React projects and routes to React-specific workflows with React 18 best practices.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+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);
+
+const pkg = JSON.parse(
+  await fs.readFile(path.join(__dirname, "..", "package.json"), "utf-8")
+);
+
+const SOURCE_DIR = path.join(__dirname, "..", "templates", "orchestration");
+const WORKFLOWS_DIR = path.join(SOURCE_DIR, "workflows");
+const DEST_NAME = ".orchestration";
+
+const ORCHESTRATION_INSTRUCTION = `
+
+## Orchestration
+
+For complex tasks, refer to .orchestration/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 findOrchestraMdFiles(projectDir) {
+  const entries = await fs.readdir(projectDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.toLowerCase() === "orchestration.md")
+    .map((entry) => entry.name);
+}
+
+async function updateOrchestraMd(projectDir) {
+  const mdFiles = await findOrchestraMdFiles(projectDir);
+
+  if (mdFiles.length === 0) {
+    const newFilePath = path.join(projectDir, "ORCHESTRATION.md");
+    await fs.writeFile(newFilePath, `# ORCHESTRATION.md${ORCHESTRATION_INSTRUCTION}`);
+    console.log("  Created: ORCHESTRATION.md");
+    return;
+  }
+
+  for (const fileName of mdFiles) {
+    const mdPath = path.join(projectDir, fileName);
+    const content = await fs.readFile(mdPath, "utf-8");
+
+    if (content.includes(".orchestration/orchestration.md")) {
+      console.log(`  Skipped: ${fileName} already references orchestration.md`);
+      continue;
+    }
+
+    await fs.appendFile(mdPath, ORCHESTRATION_INSTRUCTION);
+    console.log(`  Updated: ${fileName}`);
+  }
+}
+
+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("Agent 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 w of ROOT_WORKFLOWS) {
+    allFiles.push({ folder: null, file: w.name });
+  }
+
+  return allFiles;
+}
+
+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 {
+      const src = path.join(WORKFLOWS_DIR, file);
+      const dest = path.join(workflowsDir, file);
+      await copyFile(src, dest);
+    }
+  }
+}
+
+async function main(options) {
+  const targetDir = path.join(process.cwd(), DEST_NAME);
+
+  try {
+    let selectedFiles;
+
+    if (options.all) {
+      selectedFiles = await getAllWorkflows();
+      console.log("Agent 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 updateOrchestraMd(process.cwd());
+    console.log("\nDone! Orchestration files have been added to .orchestration/");
+  } catch (error) {
+    console.error("Error copying files:", error.message);
+    process.exit(1);
+  }
+}
+
+const program = new Command();
+
+program
+  .name("agentic-orchestration")
+  .description("Scaffolds agent 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

@@ -0,0 +1,34 @@
+{
+  "name": "agentic-orchestration",
+  "version": "1.0.7",
+  "description": "CLI tool to scaffold agent orchestration workflows into your project",
+  "bin": {
+    "agentic-orchestration": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node bin/cli.js --help"
+  },
+  "keywords": [
+    "agent",
+    "orchestration",
+    "ai",
+    "scaffolding",
+    "cli",
+    "react",
+    "workflows"
+  ],
+  "author": "Enrique MD",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "bin",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "@inquirer/prompts": "^7.0.0"
+  }
+}

package/templates/orchestration/orchestration.md

@@ -0,0 +1,52 @@
+# 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/orchestration/workflows/react/bugfix.md

@@ -0,0 +1,32 @@
+# React Bugfix Workflow
+
+## 1. Reproduce
+
+- Confirm bug exists | find minimal repro
+- Check Strict Mode behavior
+- Answer: Expected vs actual? React 18 concurrent issue?
+
+## 2. Locate Root Cause
+
+| Common React 18 Issues |
+|------------------------|
+| Effects missing cleanup |
+| Stale closures in effects |
+| Concurrent rendering race conditions |
+| Automatic batching changes |
+
+## 3. Fix
+
+- Keep changes within affected feature folder
+- Add cleanup: `return () => controller.abort()`
+- Fix stale closures with proper deps
+
+## 4. Verify
+
+- Confirm fix | test with Strict Mode
+- Add regression test
+
+## Constraints
+
+- Smallest fix only | NO refactoring
+- NO barrel exports | note other issues separately

package/templates/orchestration/workflows/react/docs.md

@@ -0,0 +1,59 @@
+# React Documentation Workflow
+
+> Document architecture correctly. See orchestration.md for patterns.
+
+## Before Writing
+
+MUST answer:
+- Who is the audience?
+- What should they be able to do after reading?
+- What existing docs need to stay in sync?
+
+## Process
+
+### 1. Understand the Subject
+- Read the code being documented
+- Try it yourself if possible
+- Identify non-obvious behavior or gotchas
+
+### 2. Check Existing Docs
+- Find related documentation
+- Identify what's missing or outdated
+- Note the existing style and format
+
+### 3. Write
+
+Adapt this template as needed:
+
+```markdown
+# {Name}
+
+Brief description.
+
+## Location
+`features/{feature}/components/{Name}/{Name}.tsx`
+
+## Import
+import { Name } from '@/features/{feature}/components/{Name}/{Name}'
+
+## Usage
+<Name prop="value" />
+
+## Props/Parameters (if applicable)
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+
+## Related
+- Links to related components/hooks
+```
+
+### 4. Validate
+- Code examples actually work
+- Import paths are direct (not barrel)
+- Links are valid
+
+## Constraints
+
+- MUST explain why, not just what
+- MUST show direct import paths in examples
+- MUST update related docs to stay consistent

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

@@ -0,0 +1,37 @@
+# React Feature Workflow
+
+## 1. Architecture
+
+**IF not specified:** Use `AskUserQuestion` (header: "Architecture")
+
+| Architecture | Structure |
+|--------------|-----------|
+| Feature-driven | `features/{name}/components\|hooks\|utils/` |
+| Flat feature-driven | `features/{name}/` flat files |
+| Atomic design | `atoms\|molecules\|organisms\|templates/` |
+
+**IF project has patterns:** Follow existing, skip question.
+
+## 2. Context
+
+- Read related code, identify target folder
+- Check similar implementations, reusable hooks/utils
+- Answer: What problem? Minimal version? Which folder?
+
+## 3. Implement
+
+**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
+
+## 4. Validate
+
+- Run tests for regressions
+- Add tests for new code
+- Test loading/error states
+- Remove debug code
+
+## Constraints
+
+- NO `index.ts`/`index.tsx` | import from file directly
+- Match existing style | no extra features

package/templates/orchestration/workflows/react/performance.md

@@ -0,0 +1,59 @@
+# React Performance Workflow
+
+> Architecture rules: See orchestration.md. Violations block merge.
+
+## Before Coding
+
+MUST answer:
+- What is the specific performance problem?
+- How will I measure improvement?
+- Is this a real bottleneck or premature optimization?
+
+## Process
+
+### 1. Measure First
+- Profile with React DevTools Profiler
+- Identify components that re-render unnecessarily
+- Check bundle size with build analyzer
+- Measure actual user-facing metrics (not just hunches)
+
+### 2. Identify Root Cause
+
+**Common issues:**
+- Components re-rendering when props haven't changed
+- Expensive calculations on every render
+- Large bundle from unused dependencies
+- Missing code splitting on routes
+
+### 3. Optimize
+
+**Prevent unnecessary re-renders:**
+```tsx
+// Memoize components that receive stable props
+const MemoizedList = memo(List)
+
+// Memoize callbacks passed to children
+const handleClick = useCallback(() => {
+  doSomething(id)
+}, [id])
+
+// Memoize expensive derived values
+const sorted = useMemo(() => sortItems(items), [items])
+```
+
+**Reduce bundle size:**
+- Lazy load routes with `React.lazy` + `Suspense`
+- Replace heavy libraries with lighter alternatives
+- Use tree-shakeable imports
+
+### 4. Verify
+- Re-profile to confirm improvement
+- Ensure no regressions in functionality
+- Document the optimization and why it helped
+
+## Constraints
+
+- NEVER optimize without measuring first
+- NEVER add memo/useMemo/useCallback everywhere "just in case"
+- MUST prove the optimization helps with real measurements
+- Keep optimizations minimal and targeted

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

@@ -0,0 +1,19 @@
+# Pull Request Workflow
+
+## Process
+
+1. Read diff (current branch vs main/master)
+2. Analyze changes
+3. Output title + description
+
+## Output
+
+```
+PR Title: <imperative mood>
+Description: <2-3 sentences: what + why>
+```
+
+## Constraints
+
+- Imperative mood ("Add" not "Added") | mention breaking changes
+- Output only | NO branch/push/remote PR creation

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

@@ -0,0 +1,32 @@
+# React Refactor Workflow
+
+## 1. Safety Net
+
+- Run tests | add if coverage insufficient
+- Answer: What improvement? How verify unchanged behavior?
+
+## 2. Plan
+
+- Map imports/dependencies | identify all callers
+- Break into small, safe steps
+
+## 3. Execute
+
+One change type at a time | run tests after each:
+
+| Change Types |
+|--------------|
+| Rename files to match folders |
+| Barrel → direct imports |
+| Extract logic into hooks |
+| Split large components |
+
+## 4. Validate
+
+- All tests pass | no `index.ts`/`index.tsx`
+- Entry points match folder names
+
+## Constraints
+
+- Structure only, NOT behavior | NO bug fixes
+- One change type at a time | note issues separately

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

@@ -0,0 +1,46 @@
+# React Code Review Workflow
+
+## 1. Understand
+
+- Read PR description | review diff scope
+- Answer: What is the goal? What files changed?
+
+## 2. Architecture Checklist
+
+| 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 |
+
+## 3. React Patterns Checklist
+
+| 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 |
+
+## 4. Code Quality Checklist
+
+| Check | Rule |
+|-------|------|
+| Debug | No console.log/debugger |
+| Imports | No unused |
+| Types | No unjustified `any` |
+| Tests | Cover new functionality |
+| Scope | No unrelated changes |
+
+## 5. Feedback
+
+- **Blocking:** Must fix (bugs, architecture violations)
+- **Suggestion:** Improvements | **Question:** Clarification
+
+## Constraints
+
+- NO approval with violations | must understand code
+- Specific + actionable | suggest fixes, not just problems

package/templates/orchestration/workflows/todo.md

@@ -0,0 +1,19 @@
+# TODO Workflow
+
+> Use for tasks with 3+ steps requiring tracking
+
+## Process
+
+1. **Analyze**: Read codebase, identify steps, estimate complexity
+2. **Create**: One actionable TODO per distinct step, prioritize by dependencies
+3. **Execute**: ONE item `in_progress` at a time, update status immediately
+4. **Manage**: Add/cancel items as needed, break down complex items
+
+## Rules
+
+- Use only for complex tasks (3+ steps)
+- Single `in_progress` item maximum
+- Real-time status updates
+- Brief, actionable descriptions
+- Complete current before starting next
+- Save TODO files in project root as `{sensibleName}_TODO.md`