claude-orchestration 1.0.0 → 1.0.2

package/README.md

@@ -18,6 +18,8 @@ This will create a `.claude/` directory with workflow templates:
       feature.md
       bugfix.md
       refactor.md
+      performance.md
+      review.md
       pr.md
       docs.md
 ```
@@ -34,7 +36,9 @@ This will create a `.claude/` directory with workflow templates:
 | `feature.md` | Building new functionality |
 | `bugfix.md` | Diagnosing and fixing bugs |
 | `refactor.md` | Improving code without behavior changes |
-| `pr.md` | Creating pull requests |
+| `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.

package/bin/cli.js

@@ -37,7 +37,6 @@ if (process.argv.includes("--version") || process.argv.includes("-v")) {
 
 const SOURCE_DIR = path.join(__dirname, "..", "templates", "claude");
 const DEST_NAME = ".claude";
-const CLAUDE_MD = "CLAUDE.md";
 
 const ORCHESTRATION_INSTRUCTION = `
 
@@ -46,28 +45,34 @@ const ORCHESTRATION_INSTRUCTION = `
 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 findClaudeMdFiles(projectDir) {
+  const entries = await fs.readdir(projectDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.toLowerCase() === "claude.md")
+    .map((entry) => entry.name);
 }
 
 async function updateClaudeMd(projectDir) {
-  const claudeMdPath = path.join(projectDir, CLAUDE_MD);
+  const claudeMdFiles = await findClaudeMdFiles(projectDir);
+
+  if (claudeMdFiles.length === 0) {
+    const newFilePath = path.join(projectDir, "CLAUDE.md");
+    await fs.writeFile(newFilePath, `# CLAUDE.md${ORCHESTRATION_INSTRUCTION}`);
+    console.log("  Created: CLAUDE.md");
+    return;
+  }
 
-  if (await fileExists(claudeMdPath)) {
+  for (const fileName of claudeMdFiles) {
+    const claudeMdPath = path.join(projectDir, fileName);
     const content = await fs.readFile(claudeMdPath, "utf-8");
 
     if (content.includes(".claude/orchestration.md")) {
-      console.log(`  Skipped: ${CLAUDE_MD} already references orchestration.md`);
-      return;
+      console.log(`  Skipped: ${fileName} already references orchestration.md`);
+      continue;
     }
 
     await fs.appendFile(claudeMdPath, ORCHESTRATION_INSTRUCTION);
-    console.log(`  Updated: ${CLAUDE_MD}`);
+    console.log(`  Updated: ${fileName}`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-orchestration",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI tool to scaffold Claude orchestration workflows into your project",
   "bin": {
     "claude-orchestration": "bin/cli.js"

package/templates/claude/orchestration.md

@@ -21,7 +21,9 @@ If React indicators are present → use `workflows/react/` directory
 | `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 |
+| `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 |
 
 **Workflow Path:**
@@ -34,3 +36,40 @@ If React indicators are present → use `workflows/react/` directory
 - 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
+
+---
+
+## React Architecture Rules
+
+All React workflows MUST follow these rules. Violations block merge.
+
+### Structure
+- **Feature-based**: Organize by feature, not by type
+- **No barrels**: NEVER use `index.ts` to re-export from a folder
+- **Entry 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
+```
+features/
+  auth/
+    auth.tsx              # 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 Convention
+```tsx
+// CORRECT: Direct imports
+import { LoginForm } from '@/features/auth/components/LoginForm/LoginForm'
+import { useAuth } from '@/features/auth/auth.hooks'
+
+// WRONG: Barrel imports - NEVER do this
+import { LoginForm } from '@/features/auth/components'
+import { useAuth } from '@/features/auth'
+```

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

@@ -1,38 +1,35 @@
 # React Bugfix Workflow
 
-## Architecture Rules
+> Architecture rules: See orchestration.md. Violations block merge.
 
-- **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 Coding
 
-## Before Starting
-
-- [ ] Can I reproduce the bug?
-- [ ] What is the expected vs actual behavior?
-- [ ] Is this related to React 18 concurrent features?
+MUST answer:
+- Can I reproduce the bug?
+- What is 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
+- Check if it only occurs in Strict Mode
+- Find minimal reproduction case
 
-### 2. Locate the Root Cause
+### 2. Locate Root Cause
 
 **Common React 18 issues:**
-- Effects with missing cleanup functions
-- Effects depending on stale closures
+- Effects missing cleanup functions
+- Effects with 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.
+MUST keep changes within affected feature folder.
 
 ```tsx
-// Fix: Add cleanup for effects
+// Example: Add cleanup for effects
 useEffect(() => {
   const controller = new AbortController()
   fetchData(controller.signal)
@@ -41,12 +38,13 @@ useEffect(() => {
 ```
 
 ### 4. Verify
-- Confirm the bug is fixed
+- Confirm bug is fixed
 - Test with Strict Mode enabled
-- Add a test that would have caught this bug
+- Add test that would have caught this bug
 
-## Reminders
+## Constraints
 
-- A bugfix is not an opportunity to refactor
-- The best fix is usually the smallest fix
-- If you discover other issues, note them separately
+- 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

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

@@ -1,203 +1,59 @@
 # React Documentation Workflow
 
-## React 18 Best Practices
+> Document architecture correctly. See orchestration.md for patterns.
 
-### 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 Writing
 
-## 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?
+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 or feature being documented
+- Read the code being documented
 - Try it yourself if possible
-- Note any React 18-specific behavior or patterns
-- Identify any non-obvious behavior or gotchas
+- 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
-- 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'
-```
+Adapt this template as needed:
 
-**Document React 18 patterns:**
 ```markdown
-## Component Patterns
+# {Name}
 
-### 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.
+Brief description.
 
 ## Location
-
-`features/{feature}/components/ComponentName/ComponentName.tsx`
+`features/{feature}/components/{Name}/{Name}.tsx`
 
 ## Import
-
-import { ComponentName } from '@/features/{feature}/components/ComponentName/ComponentName'
-
-## Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| ... | ... | ... | ... |
+import { Name } from '@/features/{feature}/components/{Name}/{Name}'
 
 ## Usage
+<Name prop="value" />
 
-<ComponentName prop="value" />
+## Props/Parameters (if applicable)
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
 
 ## Related
-
-- [RelatedComponent](./RelatedComponent.md)
-- [useRelatedHook](../hooks.md#userelatedhook)
+- Links to related components/hooks
 ```
 
-### 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.
-```
+### 4. Validate
+- Code examples actually work
+- Import paths are direct (not barrel)
+- Links are valid
 
-## Reminders
+## Constraints
 
-- 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
+- MUST explain why, not just what
+- MUST show direct import paths in examples
+- MUST update related docs to stay consistent

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

@@ -1,99 +1,58 @@
 # React Feature Workflow
 
-## React 18 Best Practices
+> Architecture rules: See orchestration.md. Violations block merge.
 
-### 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 Coding
 
-### 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?
+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?
 
 ## Process
 
-### 1. Understand the Context
+### 1. Understand 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
+- Identify the target feature folder
+- Check for similar implementations
+- Review reusable hooks and utilities
 
-### 2. Plan the Implementation
-- Break down into small, testable pieces
-- Plan the component hierarchy
+### 2. Plan Implementation
+- Break into small, testable pieces
+- Plan component hierarchy
 - Identify shared vs feature-specific code
-- Design state management approach (local state, context, or external)
+- Design state approach (local, context, or external)
 
-### 3. Implement with React 18 Patterns
+### 3. Implement
 
-**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`
+**Components:**
+- Function components only
+- `useState`/`useReducer` for local state
+- `useTransition` for non-urgent updates
+- `useDeferredValue` for expensive computations
+- `Suspense` for lazy-loaded components
 
 **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`
+- Components handle rendering; hooks handle logic
+- Name descriptively: `useAuthState`, `useFormValidation`
+- Place in `{feature}.hooks.ts`
 
-**State Management:**
+**State:**
 - 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
+- Prefer composition over prop drilling
+- `useSyncExternalStore` for external state
 
 ### 4. Validate
-- Run existing tests to catch regressions
-- Add tests for new components and hooks
+- Run existing tests for regressions
+- Add tests for new components/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
+- Remove debugging code and unused imports
 
-## Reminders
+## Constraints
 
-- 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
+- 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

package/templates/claude/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/claude/workflows/react/pr.md

@@ -2,21 +2,23 @@
 
 ## 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
+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
 
 ## Output Format
 
 ```
-PR Name: <concise title describing the change>
+PR Title: <concise title>
 
 Description:
-<2-3 sentences summarizing what changed and why>
+<2-3 sentences: what changed and why>
 ```
 
-## Guidelines
+## Constraints
 
-- 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
+- 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

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

@@ -1,52 +1,43 @@
 # React Refactor Workflow
 
-## Architecture Rules
+> Architecture rules: See orchestration.md. Violations block merge.
 
-- **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 Coding
 
-## Before Starting
-
-- [ ] What specific improvement am I making?
-- [ ] Is there adequate test coverage?
-- [ ] How will I verify behavior is unchanged?
+MUST answer:
+- 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
+- Run tests to confirm they pass
 - Add tests if coverage is insufficient
 
-### 2. Plan the Refactor
+### 2. Plan
 - Map all imports and dependencies
-- Identify all callers of components and hooks
+- Identify all callers of affected code
 - Break into small, safe steps
 
 ### 3. Execute Incrementally
 
-**Update imports to direct paths:**
-```tsx
-// Before (barrel)
-import { Button } from '@/components'
+Make one type of change at a time. Examples:
 
-// After (direct)
-import { Button } from '@/shared/components/Button/Button'
-```
+- Rename files to match folder names
+- Convert barrel imports to direct imports
+- Extract logic into hooks
+- Split large components
 
-**Rename entry points:**
-```
-Button/index.tsx  →  Button/Button.tsx
-```
+Run tests after each step.
 
 ### 4. Validate
 - All tests pass
 - No `index.ts` or `index.tsx` files remain
 - All entry points match folder names
 
-## Reminders
+## Constraints
 
-- Refactoring changes structure, not behavior
-- If you find bugs, fix them separately
-- Keep scope contained—one feature at a time
+- Refactoring changes structure, NOT behavior
+- NEVER fix bugs during refactor—note them separately
+- MUST keep scope contained: one change type at a time

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

@@ -0,0 +1,54 @@
+# React Code Review Workflow
+
+> Architecture rules: See orchestration.md. Violations block merge.
+
+## Before Reviewing
+
+MUST answer:
+- What is this change trying to accomplish?
+- What files are modified?
+
+## Process
+
+### 1. Understand the Change
+- Read the PR description
+- Review the diff to understand scope
+- Check if the approach makes sense for the goal
+
+### 2. Check Architecture Compliance
+
+- [ ] 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
+
+### 3. Check React Patterns
+
+- [ ] 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
+
+### 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
+
+## 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