claude-orchestration 1.0.0

package/README.md

@@ -0,0 +1,44 @@
+# claude-orchestration
+
+CLI tool to scaffold Claude orchestration workflows into your project.
+
+## Usage
+
+```bash
+npx claude-orchestration
+```
+
+This will create a `.claude/` directory with workflow templates:
+
+```
+.claude/
+  orchestration.md
+  workflows/
+    react/
+      feature.md
+      bugfix.md
+      refactor.md
+      pr.md
+      docs.md
+```
+
+## What it does
+
+1. Copies workflow templates to `.claude/` in your project
+2. Appends orchestration reference to your `CLAUDE.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 |
+| `pr.md` | Creating pull requests |
+| `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,106 @@
+#!/usr/bin/env node
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+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 SOURCE_DIR = path.join(__dirname, "..", "templates", "claude");
+const DEST_NAME = ".claude";
+const CLAUDE_MD = "CLAUDE.md";
+
+const ORCHESTRATION_INSTRUCTION = `
+
+## Orchestration
+
+For complex tasks, refer to .claude/orchestration.md for available workflows.
+`;
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function updateClaudeMd(projectDir) {
+  const claudeMdPath = path.join(projectDir, CLAUDE_MD);
+
+  if (await fileExists(claudeMdPath)) {
+    const content = await fs.readFile(claudeMdPath, "utf-8");
+
+    if (content.includes(".claude/orchestration.md")) {
+      console.log(`  Skipped: ${CLAUDE_MD} already references orchestration.md`);
+      return;
+    }
+
+    await fs.appendFile(claudeMdPath, ORCHESTRATION_INSTRUCTION);
+    console.log(`  Updated: ${CLAUDE_MD}`);
+  }
+}
+
+async function copyDir(src, dest) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await fs.copyFile(srcPath, destPath);
+      console.log(`  Created: ${path.relative(process.cwd(), destPath)}`);
+    }
+  }
+}
+
+async function main() {
+  const targetDir = path.join(process.cwd(), DEST_NAME);
+
+  console.log("Claude Orchestration Setup\n");
+
+  try {
+    await copyDir(SOURCE_DIR, targetDir);
+    await updateClaudeMd(process.cwd());
+    console.log("\nDone! Orchestration files have been added to .claude/");
+  } catch (error) {
+    console.error("Error copying files:", error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "claude-orchestration",
+  "version": "1.0.0",
+  "description": "CLI tool to scaffold Claude orchestration workflows into your project",
+  "bin": {
+    "claude-orchestration": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node bin/cli.js --help"
+  },
+  "keywords": [
+    "claude",
+    "orchestration",
+    "ai",
+    "scaffolding",
+    "cli",
+    "react",
+    "workflows"
+  ],
+  "author": "Enrique MD",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "bin",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/templates/claude/orchestration.md

@@ -0,0 +1,36 @@
+# 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 |
+| `pr.md` | Creating and preparing pull requests |
+| `docs.md` | Writing or updating documentation |
+
+**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

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

@@ -0,0 +1,52 @@
+# React Bugfix Workflow
+
+## Architecture Rules
+
+- **Feature architecture**: Organize by feature, not by type
+- **No barrel exports**: Never use `index.ts` to re-export
+- **Entry point naming**: File must match folder name (`Button/Button.tsx`)
+
+## Before Starting
+
+- [ ] Can I reproduce the bug?
+- [ ] What is the expected vs actual behavior?
+- [ ] Is this related to React 18 concurrent features?
+
+## Process
+
+### 1. Reproduce and Isolate
+- Confirm the bug exists
+- Check if it only occurs in Strict Mode (development)
+- Find the minimal reproduction case
+
+### 2. Locate the Root Cause
+
+**Common React 18 issues:**
+- Effects with missing cleanup functions
+- Effects depending on stale closures
+- Race conditions from concurrent rendering
+- Automatic batching behavior changes
+
+### 3. Fix
+
+Keep changes within the affected feature folder. Don't introduce barrel exports.
+
+```tsx
+// Fix: Add cleanup for effects
+useEffect(() => {
+  const controller = new AbortController()
+  fetchData(controller.signal)
+  return () => controller.abort()
+}, [])
+```
+
+### 4. Verify
+- Confirm the bug is fixed
+- Test with Strict Mode enabled
+- Add a test that would have caught this bug
+
+## Reminders
+
+- A bugfix is not an opportunity to refactor
+- The best fix is usually the smallest fix
+- If you discover other issues, note them separately

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

@@ -0,0 +1,203 @@
+# React Documentation Workflow
+
+## React 18 Best Practices
+
+### Architecture Rules
+- **Feature architecture**: Organize by feature, not by type
+- **No barrel exports**: Never use `index.ts` to re-export from a folder
+- **Entry point naming**: Main file must match folder name (`Button/Button.tsx`, not `Button/index.tsx`)
+- **Colocation**: Keep related files together (component, hooks, types, tests, styles)
+
+## Before Starting
+
+- [ ] Who is the audience for this documentation?
+- [ ] What should they be able to do after reading it?
+- [ ] What existing docs need to stay in sync?
+- [ ] Does this document React 18 patterns correctly?
+
+## Process
+
+### 1. Understand the Subject
+- Read the code or feature being documented
+- Try it yourself if possible
+- Note any React 18-specific behavior or patterns
+- Identify any non-obvious behavior or gotchas
+
+### 2. Check Existing Docs
+- Find related documentation
+- Identify what's missing or outdated
+- Note the existing style and format
+- Check for outdated React patterns (class components, lifecycle methods)
+
+### 3. Write
+
+**Document the architecture:**
+```markdown
+## File Structure
+
+features/
+  auth/
+    auth.tsx              # Main entry point
+    auth.hooks.ts         # useAuth, useSession
+    auth.types.ts         # AuthState, User
+    components/
+      LoginForm/
+        LoginForm.tsx     # Login form component
+```
+
+**Document import conventions:**
+```markdown
+## Importing
+
+Always use direct imports:
+
+// Correct
+import { LoginForm } from '@/features/auth/components/LoginForm/LoginForm'
+import { useAuth } from '@/features/auth/auth.hooks'
+
+// Incorrect - never use barrel imports
+import { LoginForm } from '@/features/auth/components'
+```
+
+**Document React 18 patterns:**
+```markdown
+## Component Patterns
+
+### Using Transitions
+For non-urgent state updates, use useTransition:
+
+const [isPending, startTransition] = useTransition()
+
+startTransition(() => {
+  setFilteredResults(results)
+})
+
+### Suspense for Loading States
+Wrap async components with Suspense:
+
+<Suspense fallback={<Skeleton />}>
+  <AsyncComponent />
+</Suspense>
+```
+
+### 4. Validate
+- Code examples actually work
+- Import paths follow the direct import convention
+- Examples use React 18 patterns (not deprecated ones)
+- Links are valid
+- Instructions produce expected results
+- No references to removed features or old patterns
+
+### 5. Review
+- Read it from a newcomer's perspective
+- Check for outdated React terminology
+- Ensure logical flow
+- Verify architecture rules are explained clearly
+
+## Documentation Templates
+
+### Component Documentation
+```markdown
+# ComponentName
+
+Brief description of what the component does.
+
+## Location
+
+`features/{feature}/components/ComponentName/ComponentName.tsx`
+
+## Import
+
+import { ComponentName } from '@/features/{feature}/components/ComponentName/ComponentName'
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| ... | ... | ... | ... |
+
+## Usage
+
+<ComponentName prop="value" />
+
+## Related
+
+- [RelatedComponent](./RelatedComponent.md)
+- [useRelatedHook](../hooks.md#userelatedhook)
+```
+
+### Hook Documentation
+```markdown
+# useHookName
+
+Brief description of what the hook does.
+
+## Location
+
+`features/{feature}/{feature}.hooks.ts`
+
+## Import
+
+import { useHookName } from '@/features/{feature}/{feature}.hooks'
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+
+## Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+
+## Usage
+
+const { data, isLoading } = useHookName(param)
+
+## React 18 Notes
+
+Any specific React 18 considerations (Suspense, transitions, etc.)
+```
+
+### Feature Documentation
+```markdown
+# Feature Name
+
+## Overview
+
+What this feature does and why it exists.
+
+## Architecture
+
+features/
+  {feature}/
+    {feature}.tsx         # Entry point
+    {feature}.hooks.ts    # Hooks
+    {feature}.types.ts    # Types
+    components/           # Feature components
+
+## Key Components
+
+- **ComponentA**: Description
+- **ComponentB**: Description
+
+## Hooks
+
+- **useHookA**: Description
+- **useHookB**: Description
+
+## Usage
+
+How to use this feature in the application.
+```
+
+## Reminders
+
+- Good docs explain why, not just what
+- Keep examples simple and focused
+- Always show correct import paths (direct, not barrel)
+- Update related docs to stay consistent
+- Remove documentation for removed features
+- Match the tone and style of existing project docs
+- Ensure all code examples use React 18 patterns
+- Document any migration notes from older patterns

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

@@ -0,0 +1,99 @@
+# React Feature Workflow
+
+## React 18 Best Practices
+
+### Architecture Rules
+- **Feature architecture**: Organize by feature, not by type
+- **No barrel exports**: Never use `index.ts` to re-export from a folder
+- **Entry point naming**: Main file must match folder name (`Button/Button.tsx`, not `Button/index.tsx`)
+- **Colocation**: Keep related files together (component, hooks, types, tests, styles)
+
+### File Structure Example
+```
+features/
+  auth/
+    auth.tsx              # Feature entry point (matches folder name)
+    auth.hooks.ts         # Feature-specific hooks
+    auth.types.ts         # Feature-specific types
+    auth.test.tsx         # Feature tests
+    components/
+      LoginForm/
+        LoginForm.tsx     # Component entry (matches folder name)
+        LoginForm.test.tsx
+```
+
+### Import Rules
+```tsx
+// CORRECT: Direct imports
+import { LoginForm } from '@/features/auth/components/LoginForm/LoginForm'
+import { useAuth } from '@/features/auth/auth.hooks'
+
+// WRONG: Barrel imports
+import { LoginForm } from '@/features/auth/components'
+import { useAuth } from '@/features/auth'
+```
+
+## Before Starting
+
+- [ ] What problem does this feature solve?
+- [ ] What's the minimal viable version?
+- [ ] Which feature folder does this belong in?
+- [ ] Are there existing patterns in the codebase to follow?
+
+## Process
+
+### 1. Understand the Context
+- Read related existing code
+- Identify the feature folder this belongs in
+- Check for similar implementations to learn from
+- Review existing hooks and utilities that can be reused
+
+### 2. Plan the Implementation
+- Break down into small, testable pieces
+- Plan the component hierarchy
+- Identify shared vs feature-specific code
+- Design state management approach (local state, context, or external)
+
+### 3. Implement with React 18 Patterns
+
+**Component Patterns:**
+- Use function components exclusively
+- Prefer `useState` and `useReducer` for local state
+- Use `useTransition` for non-urgent updates
+- Use `useDeferredValue` for expensive computations
+- Wrap lazy-loaded components with `Suspense`
+
+**Hooks:**
+- Extract reusable logic into custom hooks
+- Abstract complex business logic to hooks—components should only handle rendering
+- Name hooks descriptively: `useAuthState`, `useFormValidation`
+- Keep hooks focused on single responsibilities
+- Place feature hooks in `{feature}.hooks.ts`
+
+**State Management:**
+- Lift state only as high as necessary
+- Use composition over prop drilling
+- Consider React Context for feature-wide state
+- Use `useSyncExternalStore` for external state integration
+
+### 4. Validate
+- Run existing tests to catch regressions
+- Add tests for new components and hooks
+- Test loading and error states
+- Verify Suspense boundaries work correctly
+- Ensure types pass with strict mode
+
+### 5. Clean Up
+- Remove any debugging code
+- Ensure code follows project conventions
+- Check for unused imports or variables
+- Verify no barrel exports were introduced
+
+## Reminders
+
+- Create new files following the naming convention (folder name = entry file name)
+- Never create `index.ts` or `index.tsx` files
+- Import directly from the file, not from folder paths
+- Match the style of surrounding code
+- Don't add features beyond what was requested
+- Use Suspense for code splitting, not just loading states

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

@@ -0,0 +1,22 @@
+# Pull Request Workflow
+
+## Process
+
+1. Get the diff between current branch and main/master
+2. Analyze the changes to understand what was done
+3. Generate a PR name and description
+
+## Output Format
+
+```
+PR Name: <concise title describing the change>
+
+Description:
+<2-3 sentences summarizing what changed and why>
+```
+
+## Guidelines
+
+- PR name should be imperative mood ("Add feature" not "Added feature")
+- Keep description brief and focused on the "what" and "why"
+- Mention breaking changes if any

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

@@ -0,0 +1,52 @@
+# React Refactor Workflow
+
+## Architecture Rules
+
+- **Feature architecture**: Organize by feature, not by type
+- **No barrel exports**: Never use `index.ts` to re-export
+- **Entry point naming**: File must match folder name (`Button/Button.tsx`)
+- **Colocation**: Keep related files together
+
+## Before Starting
+
+- [ ] What specific improvement am I making?
+- [ ] Is there adequate test coverage?
+- [ ] How will I verify behavior is unchanged?
+
+## Process
+
+### 1. Ensure Safety Net
+- Run tests to confirm they pass before changes
+- Add tests if coverage is insufficient
+
+### 2. Plan the Refactor
+- Map all imports and dependencies
+- Identify all callers of components and hooks
+- Break into small, safe steps
+
+### 3. Execute Incrementally
+
+**Update imports to direct paths:**
+```tsx
+// Before (barrel)
+import { Button } from '@/components'
+
+// After (direct)
+import { Button } from '@/shared/components/Button/Button'
+```
+
+**Rename entry points:**
+```
+Button/index.tsx  →  Button/Button.tsx
+```
+
+### 4. Validate
+- All tests pass
+- No `index.ts` or `index.tsx` files remain
+- All entry points match folder names
+
+## Reminders
+
+- Refactoring changes structure, not behavior
+- If you find bugs, fix them separately
+- Keep scope contained—one feature at a time