claude-code-orchestrator-kit 1.2.4 → 1.2.5

package/.claude/commands/health-reuse.md

@@ -0,0 +1,327 @@
+---
+description: Code reuse detection and consolidation workflow with full cycle management
+---
+
+# Code Reuse Health Check
+
+> **PATTERN**: Agent-based orchestration (see `docs/Agents Ecosystem/AGENT-ORCHESTRATION.md` for details)
+
+Complete code duplication detection and consolidation workflow with orchestrator-worker coordination.
+
+**What it does:**
+- Full duplication detection (types, schemas, constants, utilities)
+- Staged consolidation (HIGH → MEDIUM → LOW priority)
+- Quality gates after each stage
+- Verification scan
+- Up to 3 iterations if issues remain
+- Comprehensive final report
+
+**No configuration needed** - runs comprehensive checks always.
+
+---
+
+## Your Task
+
+### Step 1: Phase 0 - Invoke Orchestrator (Pre-flight)
+
+Use Task tool to invoke reuse-orchestrator for pre-flight validation:
+
+```
+subagent_type: "reuse-orchestrator"
+description: "Reuse orchestrator pre-flight"
+prompt: "Execute Phase 0: Pre-flight Validation
+
+Tasks:
+1. Validate environment (package.json, scripts, git status)
+2. Initialize progress tracking via TodoWrite
+3. Initialize iteration tracking (iteration=1, max=3)
+4. Create .tmp/current/plans/reuse-detection.json for rollback tracking
+5. Report pre-flight status
+
+IMPORTANT: After completing pre-flight, create .tmp/current/plans/reuse-detection.json and return control to main session.
+
+Return the following information:
+- Pre-flight status (✅/⛔)
+- Environment validation results
+- Plan file path created
+- Ready for next phase: true/false
+"
+```
+
+**Then**: Wait for orchestrator to return.
+
+---
+
+### Step 2: Phase 1 - Invoke reuse-hunter (Detection)
+
+After orchestrator returns:
+
+1. **Read plan file** to confirm it was created:
+   ```
+   Use Read tool: .tmp/current/plans/reuse-detection.json
+   Verify nextAgent === "reuse-hunter"
+   ```
+
+2. **Invoke reuse-hunter** using Task tool:
+   ```
+   subagent_type: "reuse-hunter"
+   description: "Code duplication detection phase"
+   prompt: "Execute code duplication detection based on plan file: .tmp/current/plans/reuse-detection.json
+
+Read the plan file and execute comprehensive duplication detection:
+- Scan entire codebase for duplicated types, interfaces, Zod schemas
+- Find duplicated constants and configuration objects
+- Identify utility functions that are copied instead of imported
+- Categorize by priority (HIGH → MEDIUM → LOW)
+- Generate reuse-hunting-report.md
+
+Return to main session when complete."
+   ```
+
+**Then**: Wait for reuse-hunter to return with report.
+
+---
+
+### Step 3: Quality Gate 1 - Resume Orchestrator (Validate Detection)
+
+After reuse-hunter returns:
+
+1. **Resume orchestrator** for validation using Task tool:
+   ```
+   subagent_type: "reuse-orchestrator"
+   description: "Validate duplication detection"
+   prompt: "Execute Quality Gate 1: Detection Validation
+
+Phase: Validate reuse-hunter output
+
+Tasks:
+1. Verify reuse-hunting-report.md exists
+2. Validate report structure (required sections)
+3. Parse duplication counts by priority
+4. Run type-check validation (non-blocking warning)
+5. Report gate results
+
+IMPORTANT: After validation, if duplications found:
+- Create .tmp/current/plans/reuse-consolidation-{priority}.json for highest priority
+- Return control to main session
+
+If no duplications found or all gates fail:
+- Skip to final summary
+- Return control
+
+Return the following:
+- Gate status (✅ PASSED / ⛔ FAILED / ⚠️ WARNINGS)
+- Duplication counts by priority
+- Next phase: consolidation-high / consolidation-medium / final-summary
+- Plan file created (if applicable)
+"
+   ```
+
+**Then**: Wait for orchestrator validation results.
+
+---
+
+### Step 4: Phase 2-4 - Consolidation Stages (Iterative)
+
+After orchestrator returns with consolidation plan:
+
+**For each priority level** (HIGH → MEDIUM → LOW):
+
+1. **Check if this priority has duplications**:
+   - Read orchestrator response
+   - If orchestrator says "skip to next priority" → continue loop
+   - If orchestrator says "final summary" → go to Step 5
+
+2. **Read consolidation plan**:
+   ```
+   Use Read tool: .tmp/current/plans/reuse-consolidation-{priority}.json
+   Verify nextAgent === "reuse-fixer"
+   Verify config.priority === "{current-priority}"
+   ```
+
+3. **Invoke reuse-fixer** using Task tool:
+   ```
+   subagent_type: "reuse-fixer"
+   description: "Consolidate {priority} duplications"
+   prompt: "Execute code consolidation based on plan file: .tmp/current/plans/reuse-consolidation-{priority}.json
+
+Read the plan file and consolidate duplications for priority: {priority}
+- Read reuse-hunting-report.md for duplication list
+- For each duplication:
+  - Determine canonical location (usually shared-types)
+  - Create/update canonical file
+  - Replace duplicates with re-exports
+- Log changes to .reuse-changes.json
+- Update reuse-consolidation-implemented.md (consolidated report)
+
+Return to main session when complete."
+   ```
+
+4. **Resume orchestrator** for validation:
+   ```
+   subagent_type: "reuse-orchestrator"
+   description: "Validate {priority} consolidation"
+   prompt: "Execute Quality Gate 2: Consolidation Validation for priority={priority}
+
+Tasks:
+1. Verify reuse-consolidation-implemented.md exists
+2. Run type-check (BLOCKING)
+3. Run build (BLOCKING)
+4. Parse consolidation success rate
+5. Check if retry needed (if < 80% success)
+
+If validation PASSES and more priorities remain:
+- Create next .tmp/current/plans/reuse-consolidation-{priority}.json
+- Return control
+
+If validation FAILS:
+- Provide rollback instructions
+- Return control with error
+
+If all priorities complete:
+- Proceed to verification phase
+- Return control
+
+Return:
+- Gate status
+- Consolidation success rate
+- Next phase: consolidation-{next-priority} / verification / final-summary
+"
+   ```
+
+5. **Repeat** for next priority level.
+
+---
+
+### Step 5: Phase 5 - Verification
+
+After all consolidation stages complete:
+
+1. **Resume orchestrator** for verification:
+   ```
+   subagent_type: "reuse-orchestrator"
+   description: "Create verification plan"
+   prompt: "Execute Phase 5: Verification Preparation
+
+Create .tmp/current/plans/reuse-verification.json for re-scanning codebase.
+
+Return control with plan file path."
+   ```
+
+2. **Invoke reuse-hunter** for verification:
+   ```
+   subagent_type: "reuse-hunter"
+   description: "Verification scan"
+   prompt: "Execute verification scan based on: .tmp/current/plans/reuse-verification.json
+
+Re-scan codebase to verify consolidations. Overwrites reuse-hunting-report.md.
+
+Return when complete."
+   ```
+
+3. **Resume orchestrator** for verification validation:
+   ```
+   subagent_type: "reuse-orchestrator"
+   description: "Validate verification"
+   prompt: "Execute Quality Gate 3: Verification Validation
+
+Compare original reuse-hunting-report.md (baseline) with new scan:
+- Count duplications resolved
+- Check if new duplications introduced
+- Determine if iteration needed
+
+Return:
+- Verification status
+- Duplications remaining
+- Iteration decision: iterate / complete
+"
+   ```
+
+---
+
+### Step 6: Final Summary
+
+After all phases complete:
+
+1. **Resume orchestrator** for final summary:
+   ```
+   subagent_type: "reuse-orchestrator"
+   description: "Generate final summary"
+   prompt: "Execute Phase 7: Final Summary
+
+Generate comprehensive reuse-orchestration-summary.md:
+- All duplications detected
+- All consolidations performed
+- Success rates by priority
+- Validation results
+- Iteration summary
+- Cleanup instructions
+
+Return final summary."
+   ```
+
+2. **Display results** to user:
+   ```
+   Read reuse-orchestration-summary.md
+   Display key metrics
+   Show validation status
+   List next steps
+   ```
+
+---
+
+## Example Usage
+
+```bash
+# Run complete code reuse workflow
+/health-reuse
+```
+
+---
+
+## Architecture Notes
+
+**Orchestrator Role**:
+- Creates plan files
+- Validates worker outputs
+- Returns control to main session
+- NO direct worker invocation
+
+**Main Session Role** (this command):
+- Reads plan files
+- Invokes workers via Task tool
+- Resumes orchestrator for validation
+- Manages full cycle
+
+**Worker Role**:
+- Reads plan file
+- Executes work
+- Generates report
+- Returns to main session
+
+This pattern follows Claude Code's actual capabilities (no auto-invoke).
+
+---
+
+## Duplication Categories
+
+**Types/Interfaces** (shared-types):
+- Database types
+- API types
+- Zod schemas
+- Common enums
+
+**Constants** (shared-types):
+- Configuration objects
+- MIME types, file limits
+- Feature flags
+
+**Utilities** (shared package or re-export):
+- Helper functions
+- Validation utilities
+- Formatters
+
+**Single Source of Truth Pattern**:
+1. Canonical location: `packages/shared-types/src/`
+2. Other packages: `export * from '@megacampus/shared-types/{module}'`
+3. NEVER copy code between packages

package/.claude/commands/speckit.implement.md

@@ -14,6 +14,13 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Outline
 
+0. **Session Check** (DeksdenFlow):
+   - Invoke `resume-session` skill to check for existing session
+   - If valid session found: ask user "Resume previous session or start fresh?"
+   - If resume: load context.md and session-log.md, jump to saved phase
+   - If fresh or no session: proceed to step 1
+   - **Also**: Invoke `load-project-context` skill to load project structure map
+
 1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
 
 2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
@@ -145,6 +152,10 @@ You **MUST** consider the user input before proceeding (if not empty).
       - [EXECUTOR: MAIN]? → Execute directly if trivial, else delegate
       - [EXECUTOR: subagent-name]? → Delegate to specified subagent
    3. GATHER CONTEXT: Read existing code, search patterns, review docs, check commits
+   3.5. LIBRARY SEARCH: Before writing >20 lines of new code, search for existing npm/pypi packages
+      - Use WebSearch + Context7 to find and evaluate libraries
+      - If suitable library found: install and configure instead of implementing from scratch
+      - Check: weekly downloads >1000, recent commits, TypeScript support, no critical vulnerabilities
    4. EXECUTE:
       - Direct: Use Edit/Write tools for trivial tasks only
       - Delegated: Launch Task tool with complete context (code snippets, file paths, patterns, validation criteria)
@@ -172,6 +183,10 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Provide clear error messages with context for debugging
    - Suggest next steps if implementation cannot proceed
    - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file
+   - **Session Context** (DeksdenFlow):
+     * After completing each PHASE (not task): invoke `save-session-context` skill
+     * On error or pause: save context before stopping
+     * Log significant decisions to session-log.md (architecture choices, issue resolutions)
    - **Critical Rules**:
      * NEVER skip verification
      * NEVER proceed if task failed

package/.claude/commands/speckit.plan.md

@@ -56,7 +56,12 @@ You **MUST** consider the user input before proceeding (if not empty).
    - Rationale: [why chosen]
    - Alternatives considered: [what else evaluated]
 
-**Output**: research.md with all NEEDS CLARIFICATION resolved
+4. **Library discovery** for each planned component:
+   - Search npm/pypi for existing solutions (WebSearch + Context7)
+   - Evaluate: maintenance status (commits last 6 months), weekly downloads >1000, TypeScript support
+   - Document in research.md: chosen libraries with rationale, or justification for custom implementation
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved and library decisions documented
 
 ### Phase 1: Design & Contracts
 

package/.claude/commands/speckit.tasks.md

@@ -71,6 +71,13 @@ The tasks.md should be immediately executable - each task must be specific enoug
 
 **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
 
+**Library Evaluation (BEFORE creating implementation tasks)**:
+- For each major component (>20 lines), check if suitable library exists
+- Use research.md library decisions from planning phase
+- If suitable library found: task becomes "Install and configure {library} for {functionality}"
+- If no suitable library: task becomes "Implement {component} in {file_path}"
+- Document library choice rationale in task description when relevant
+
 ### Checklist Format (REQUIRED)
 
 Every task MUST strictly follow this format:

package/.claude/project-index.md

@@ -0,0 +1,75 @@
+# Project Index: Claude Code Orchestrator Kit
+
+> Quick navigation for AI agents. Updated: 2025-11-27
+>
+> **Purpose:** Helps agents understand project structure without reading entire codebase.
+
+## Architecture
+
+- **[CLAUDE.md](../../CLAUDE.md)** — Behavioral rules, orchestration patterns, main entry point
+- **[docs/ARCHITECTURE.md](../../docs/ARCHITECTURE.md)** — System design, C4 diagrams, workflow patterns
+- **[docs/FAQ.md](../../docs/FAQ.md)** — Common questions and answers
+
+## Core Domains
+
+### Agents (.claude/agents/)
+- **[agents/](agents/)** — 33+ specialized AI agents
+  - **[health/orchestrators/](agents/health/orchestrators/)** — Bug, security, deps, cleanup workflows
+  - **[health/workers/](agents/health/workers/)** — Bug-hunter, bug-fixer, security-scanner, etc.
+  - **[development/workers/](agents/development/workers/)** — LLM, TypeScript, cost specialists
+  - **[meta/workers/](agents/meta/workers/)** — meta-agent-v3, skill-builder-v2
+  - Pattern: Orchestrator delegates to Workers via Task tool
+
+### Commands (.claude/commands/)
+- **[commands/](commands/)** — 19+ slash commands
+  - Key: `health-*.md` — Health monitoring workflows
+  - Key: `speckit.*.md` — Specification toolkit
+  - Key: `push.md` — Release automation
+  - Pattern: Commands trigger orchestrators or direct actions
+
+### Skills (.claude/skills/)
+- **[skills/](skills/)** — 15+ reusable utilities
+  - Key: `run-quality-gate/` — Type-check, build, tests validation
+  - Key: `validate-plan-file/` — JSON schema validation
+  - Key: `rollback-changes/` — File restoration
+  - Pattern: Stateless utilities, <100 lines, invoked via Skill tool
+
+### MCP Configurations (mcp/)
+- **[mcp/](../../mcp/)** — 7 MCP server configurations
+  - Key: `.mcp.base.json` — Minimal (~600 tokens)
+  - Key: `.mcp.serena.json` — LSP semantic search (~2500 tokens)
+  - Key: `.mcp.full.json` — All servers (~6500 tokens)
+  - Pattern: switch-mcp.sh for dynamic switching
+
+## Temporary Files
+
+- **[.tmp/current/](../../.tmp/current/)** — Active workflow artifacts (git-ignored)
+  - `plans/` — Orchestrator plan files
+  - `reports/` — Worker-generated reports
+  - `session/` — Session context and logs
+
+## Configuration
+
+- **[.env.example](../../.env.example)** — Environment variables template
+- **[switch-mcp.sh](../../switch-mcp.sh)** — MCP configuration switcher
+
+## Patterns & Conventions
+
+- **Orchestration:** Main Claude Code delegates to sub-agents via Task tool
+- **Verification:** Always read modified files + run type-check after delegation
+- **Quality Gates:** type-check, build, tests must pass before commit
+- **Commits:** `/push patch` after each completed task
+
+## Key Entry Points
+
+| Purpose | File | Description |
+|---------|------|-------------|
+| Behavioral rules | `CLAUDE.md` | Read by Claude Code at session start |
+| Agent selection | `settings.local.json` | Task tool subagent_type mapping |
+| Health workflows | `commands/health-*.md` | Entry points for health checks |
+
+## Recent Changes
+
+- 2025-11-27: Added Serena MCP, DeksdenFlow integration started
+- 2025-11-27: Added reuse-hunting workflow agents
+- 2025-11-26: Updated agent configurations

package/.claude/skills/load-project-context/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: load-project-context
+description: Load project structure and navigation for complex tasks. Use when exploring unfamiliar parts of codebase or starting complex multi-file tasks.
+trigger: When exploring unfamiliar code areas, planning complex features, or needing project structure overview
+---
+
+# Load Project Context
+
+Loads the project index file to understand project structure without reading the entire codebase.
+
+## When to Use
+
+- Before exploring unfamiliar parts of the codebase
+- When planning complex multi-file changes
+- When you need to understand where specific functionality lives
+- At the start of complex orchestrator workflows
+
+## When NOT to Use
+
+- For simple, single-file tasks
+- When you already know the file locations
+- For trivial bug fixes
+
+## Algorithm
+
+1. Check if `.claude/project-index.md` exists
+2. If exists:
+   - Read the file
+   - Return the content for agent consumption
+3. If not exists:
+   - Inform that project index is not configured
+   - Suggest creating one from template
+
+## Implementation
+
+```markdown
+### Step 1: Check for project index
+
+Read the file `.claude/project-index.md`
+
+### Step 2: If file exists
+
+Return the full content. The agent should use this to:
+- Understand project structure
+- Identify key directories for the task
+- Find relevant patterns and conventions
+
+### Step 3: If file does not exist
+
+Return this message:
+"Project index not found. To create one:
+1. Copy `.claude/templates/project-index.template.md` to `.claude/project-index.md`
+2. Customize for your project structure
+3. Keep under 150 lines for token efficiency"
+```
+
+## Output Format
+
+The skill returns the project index content directly, which includes:
+- Architecture overview with links
+- Core domains with key directories
+- Patterns and conventions
+- Recent changes
+
+## Token Cost
+
+- File read: ~100-200 tokens (if index is well-maintained at <150 lines)
+- No additional processing overhead
+
+## Example Usage
+
+```
+Agent: I need to understand where authentication is handled in this project.
+
+[Invokes load-project-context skill]
+
+Skill returns project-index.md content showing:
+- Auth pattern: "Supabase Auth + RLS policies"
+- Key directory: "packages/api/src/middleware/" for auth middleware
+
+Agent now knows exactly where to look without scanning entire codebase.
+```
+
+## Maintenance
+
+The project index should be updated:
+- When major architectural changes occur
+- Weekly for "Recent Changes" section
+- When new domains/packages are added