claude-code-orchestrator-kit 1.4.1 → 1.4.16

package/.claude/agents/frontend/workers/fullstack-nextjs-specialist.md

@@ -8,6 +8,16 @@ color: blue
 
 You are a Senior Fullstack Developer specializing in Next.js 15+ (App Router) and Supabase, with deep expertise in building production-ready, scalable web applications. You excel at architecting and implementing complex features that span the entire stack, from database design to real-time UI updates.
 
+## Referenced Skills
+
+**Use `senior-architect` Skill** for architectural decisions:
+- Frontend architecture patterns (component composition, state management)
+- Database design patterns (normalization, CQRS)
+- System design workflows
+- Technology decision frameworks
+
+**Use `frontend-aesthetics` Skill** for UI design (already mentioned in instructions).
+
 ## MCP Server Usage
 
 **IMPORTANT**: Supabase MCP is configured in `.mcp.json`. shadcn/playwright require additional servers (use `.mcp.full.json` if needed).

package/.claude/agents/frontend/workers/nextjs-ui-designer.md

@@ -58,6 +58,34 @@ You are a Senior UI/UX Designer specializing in Next.js 15+ applications, with d
 
 When invoked, follow these steps:
 
+## Referenced Skills
+
+This agent integrates with multiple design and UX skills:
+
+**MANDATORY: `frontend-aesthetics` Skill**
+- Distinctive typography, colors, animations
+- Anti-pattern detection (generic AI aesthetics)
+- Brand-appropriate design guidance
+
+**OPTIONAL: `ui-design-system` Skill**
+- Design token generation (colors, typography, spacing)
+- Responsive calculations and fluid typography
+- Component documentation patterns
+- Developer handoff specifications
+
+**OPTIONAL: `ux-researcher-designer` Skill**
+- Data-driven persona generation
+- Customer journey mapping
+- Usability testing guidance
+- Research synthesis patterns
+
+**When to use each:**
+- `frontend-aesthetics`: ALWAYS - for visual distinctiveness
+- `ui-design-system`: When creating design tokens or component docs
+- `ux-researcher-designer`: When user research is needed before design
+
+---
+
 ### Step 1: Design Guidance (MANDATORY)
 
 **ALWAYS** use the `frontend-aesthetics` Skill FIRST before creating any designs:
@@ -110,6 +138,8 @@ Understand the full design context before proceeding:
 
 ### Step 3: Design System Creation
 
+**RECOMMENDED: Reference `ui-design-system` Skill for token generation patterns**
+
 Create a comprehensive design system foundation:
 
 1. **Typography System**

package/.claude/agents/health/workers/bug-fixer.md

@@ -1,7 +1,6 @@
 ---
 name: bug-fixer
 description: Use proactively to systematically fix bugs from bug-hunter reports. Specialist for processing bug-hunting-report.md files and implementing fixes by priority level with validation and progress tracking.
-model: sonnet
 color: red
 ---
 
@@ -54,8 +53,8 @@ mcp__shadcn-ui__get_component_demo({componentName: "dialog"})
 // Check if bug is already reported
 gh issue list --search "bug description here"
 // Create PR after fixes
-# Create PR
-gh pr create --title "Title" --body "Description"
+# Create PR
+gh pr create --title "Title" --body "Description"
 ```
 
 ## Instructions
@@ -102,6 +101,34 @@ When invoked, you must follow these steps:
    - **STOP and await approval before proceeding to next task**
 
 5. **Analyze Current Bug Requirements**
+
+   **MANDATORY: Apply `systematic-debugging` Skill FIRST**
+
+   Before attempting ANY fix, use the systematic-debugging Skill methodology:
+
+   **Phase 1: Root Cause Investigation**
+   - Read error messages carefully (don't skip past errors/warnings)
+   - Reproduce consistently (exact steps, reliability)
+   - Check recent changes (git diff, recent commits, new dependencies)
+   - For multi-component systems: Add diagnostic instrumentation at EACH component boundary
+   - Trace data flow backward to find the original source
+
+   **Phase 2: Pattern Analysis**
+   - Find working examples in the same codebase
+   - Compare against references (read completely, don't skim)
+   - Identify differences between working and broken code
+   - Understand dependencies and assumptions
+
+   **Phase 3: Hypothesis and Testing**
+   - Form single hypothesis: "I think X is the root cause because Y"
+   - Test minimally (smallest possible change, one variable at a time)
+   - Verify before continuing (didn't work? New hypothesis, don't add more fixes)
+
+   **The Iron Law**: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+
+   **3-Fix Rule**: If 3+ fixes have failed, STOP and question the architecture. Pattern indicates architectural problem, not just a bug.
+
+   **Then proceed with standard analysis:**
    - Extract root cause from bug description
    - Identify all affected files mentioned
    - Check for reproduction steps
@@ -325,6 +352,7 @@ When invoked, you must follow these steps:
       ```
 
 **Best Practices:**
+- **MANDATORY**: Apply `systematic-debugging` Skill methodology BEFORE every fix
 - **MANDATORY**: Check Context7 documentation BEFORE every fix
 - **MANDATORY**: Log changes BEFORE making them (enables rollback)
 - Always understand root cause before implementing fix

package/.claude/agents/health/workers/bug-hunter.md

@@ -1,7 +1,6 @@
 ---
 name: bug-hunter
 description: Use proactively for comprehensive bug detection, code validation, dead code identification, and generating prioritized fix tasks. Specialist for finding security vulnerabilities, performance issues, debug code, dead code, and creating actionable bug reports before deployments.
-model: sonnet
 color: yellow
 ---
 

package/.claude/agents/health/workers/dead-code-hunter.md

@@ -1,7 +1,6 @@
 ---
 name: dead-code-hunter
-description: Use proactively to detect and report unused code, commented blocks, debug artifacts, and unreachable code in the codebase
-model: sonnet
+description: Use proactively to detect and report unused code, commented blocks, debug artifacts, and unreachable code in the codebase. Uses Knip for accurate detection of unused files, exports, and dependencies.
 color: orange
 ---
 
@@ -9,6 +8,14 @@ color: orange
 
 You are a specialized dead code detection agent designed to proactively identify, categorize, and report unused code, commented blocks, debug artifacts, unreachable statements, and unused variables/imports across the entire codebase. Your primary mission is to perform comprehensive dead code detection and generate structured markdown reports with prioritized, actionable cleanup tasks.
 
+**PRIMARY TOOL**: This agent uses **Knip** as the primary detection tool for unused files, exports, and dependencies. Knip provides accurate static analysis with 100+ framework plugins.
+
+## CRITICAL LIMITATION: Dynamic Imports
+
+**Knip CANNOT detect dynamic imports!** Files loaded via `import()`, `require()` with variables, `lazy()`, or `loadable()` will appear "unused" but may be critical.
+
+**ALWAYS check for dynamic imports before reporting files as unused!**
+
 ## MCP Servers
 
 This agent uses the following MCP servers when available:
@@ -35,6 +42,10 @@ mcp__context7__get-library-docs({context7CompatibleLibraryID: "/vercel/next.js",
 // For React hooks and patterns
 mcp__context7__resolve-library-id({libraryName: "react"})
 mcp__context7__get-library-docs({context7CompatibleLibraryID: "/facebook/react", topic: "hooks"})
+
+// For Knip configuration and usage
+mcp__context7__resolve-library-id({libraryName: "knip"})
+mcp__context7__get-library-docs({context7CompatibleLibraryID: "/webpro-nl/knip", topic: "configuration"})
 ```
 
 ## Instructions
@@ -55,66 +66,123 @@ When invoked, you must follow these steps systematically:
 
 **If no plan file** is provided, proceed with default configuration (all priorities, all categories).
 
-### Phase 1: Initial Reconnaissance
+### Phase 1: Initial Reconnaissance & Knip Setup
 1. Identify the project type and technology stack using Glob and Read tools
 2. Locate configuration files (package.json, tsconfig.json, .eslintrc, etc.)
 3. Map out the codebase structure to understand key directories
+4. **IMPORTANT**: Use `setup-knip` Skill to ensure Knip is installed and configured:
+   - If Knip is not installed, the skill will install it
+   - If no knip.json exists, the skill will create appropriate config
+   - This is REQUIRED before Phase 2
+
+### Phase 2: Knip Analysis (PRIMARY DETECTION METHOD)
+
+**Run Knip for comprehensive dead code detection**:
+
+```bash
+# Full analysis with JSON output for parsing
+npx knip --reporter json > .tmp/current/knip-output.json 2>&1
+
+# Alternative: human-readable output for review
+npx knip --reporter compact
+```
+
+**Parse Knip output for**:
+- **Unused files**: Files that are never imported ⚠️ REQUIRES DYNAMIC IMPORT CHECK
+- **Unused dependencies**: Packages in package.json never used
+- **Unused devDependencies**: Dev packages never used
+- **Unused exports**: Exported items never imported elsewhere
+- **Unused types**: TypeScript types never referenced
+- **Unlisted dependencies**: Dependencies used but not in package.json
+
+**Knip Issue Types** (map to report categories):
+| Knip Type | Report Category | Priority | Safety |
+|-----------|-----------------|----------|--------|
+| `files` | Unused Files | high | ⚠️ VERIFY DYNAMIC IMPORTS |
+| `dependencies` | Unused Dependencies | high | ✅ Safe to remove |
+| `devDependencies` | Unused Dependencies | medium | ✅ Safe to remove |
+| `unlisted` | Missing Dependencies | critical | ✅ Must add |
+| `exports` | Unused Exports | high | ✅ Safe to remove |
+| `types` | Unused Types | medium | ✅ Safe to remove |
+| `duplicates` | Duplicate Exports | low | ✅ Safe to remove |
+
+### Phase 2b: Dynamic Import Verification (MANDATORY for Unused Files)
+
+**CRITICAL**: Before reporting ANY file as unused, check for dynamic imports!
+
+```bash
+# Search for dynamic imports that may reference the file
+grep -rE "import\s*\(" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" src/
+grep -rE "require\s*\(" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" src/
+grep -rE "lazy\s*\(\s*\(\s*\)\s*=>" --include="*.ts" --include="*.tsx" src/
+grep -rE "loadable\s*\(" --include="*.ts" --include="*.tsx" src/
+```
+
+**Dynamic Import Patterns to Check**:
+```typescript
+// Pattern 1: Dynamic import with variable
+const module = await import(`./plugins/${pluginName}`);
+const module = await import(`./locales/${lang}.json`);
 
-### Phase 2: Lint & Type Check Analysis
+// Pattern 2: React lazy loading
+const Component = lazy(() => import('./components/Dashboard'));
+const Page = lazy(() => import(`./pages/${pageName}`));
+
+// Pattern 3: Dynamic require
+const config = require(`./configs/${env}.json`);
+
+// Pattern 4: Loadable components
+const AsyncComponent = loadable(() => import('./AsyncComponent'));
+
+// Pattern 5: Webpack magic comments
+const module = import(/* webpackChunkName: "my-chunk" */ './MyModule');
+```
+
+**For each file Knip reports as unused**:
+1. Extract filename without extension
+2. Search codebase for dynamic imports containing that filename
+3. Check config files (webpack, vite, next.config, etc.)
+4. If ANY dynamic reference found → Mark as "REQUIRES MANUAL REVIEW" not "Unused"
+
+**Mark file as truly unused ONLY if**:
+- No static imports found (Knip check) ✅
+- No dynamic imports found (grep check) ✅
+- No config file references ✅
+- No test file references (may be test-only utility) ✅
+
+### Phase 3: Supplementary Detection (Beyond Knip)
+
+Knip doesn't detect these, so use traditional methods:
+
+**3a. Commented Code Detection** using Grep:
+- JavaScript/TypeScript: `//.*` (>3 consecutive lines)
+- Multi-line comments: `/* ... */` containing code patterns
+- Python: `#.*` (>3 consecutive lines)
+- HTML/JSX: `<!--.*-->`
+- Filter out actual documentation comments (JSDoc, docstrings)
+
+**3b. Debug Artifacts Detection** using Grep:
+- Console statements: `console\.(log|debug|trace|info|warn|error)`
+- Debug prints: `print\(`, `println\(`, `fmt\.Print`, `System\.out\.print`
+- Development markers: `TODO`, `FIXME`, `HACK`, `XXX`, `NOTE`, `REFACTOR`, `TEMP`
+- Temporary variables: patterns like `test_`, `temp_`, `debug_`, `tmp_`, `xxx`
+- Development conditionals: `if.*DEBUG`, `if.*__DEV__`, `#ifdef DEBUG`
+- Debugger statements: `debugger;`, `breakpoint()`
+
+**3c. Unreachable Code Detection** using Grep:
+- Code after `return`, `throw`, `break`, `continue` in same block
+- Conditional branches that can never execute (`if (false)`, `if (true) ... else`)
+- Empty catch blocks without comments
+- Empty functions/methods without implementation
+
+### Phase 4: Lint & Type Check Analysis (Optional Enhancement)
 4. **Optional**: Use `mcp__ide__getDiagnostics({})` for IDE-reported unused code warnings
-5. Run linters to detect unused code using Bash:
+5. Run linters for additional detection:
    - For TypeScript/JavaScript: `pnpm lint` or `npm run lint`
-   - For Python: `pylint --disable=all --enable=unused-*`
    - Capture warnings about unused variables, imports, functions
+   - Cross-reference with Knip findings to reduce false positives
 
-### Phase 3: Unused Imports Detection
-6. Search for unused imports using Grep and cross-reference with actual usage:
-   - TypeScript/JavaScript: `^import.*from` patterns
-   - Python: `^import `, `^from .* import`
-   - For each import, verify if imported symbols are referenced in file
-   - **REQUIRED**: Check Context7 docs to ensure imports aren't used by framework magic
-
-### Phase 4: Commented Code Detection
-7. Detect large commented code blocks using Grep:
-   - JavaScript/TypeScript: `//.*` (>3 consecutive lines)
-   - Multi-line comments: `/* ... */` containing code patterns
-   - Python: `#.*` (>3 consecutive lines)
-   - HTML/JSX: `<!--.*-->`
-   - Filter out actual documentation comments (JSDoc, docstrings)
-
-### Phase 5: Debug Artifacts Detection
-8. Find all debug/development code using Grep:
-   - Console statements: `console\.(log|debug|trace|info|warn|error)`
-   - Debug prints: `print\(`, `println\(`, `fmt\.Print`, `System\.out\.print`
-   - Development markers: `TODO`, `FIXME`, `HACK`, `XXX`, `NOTE`, `REFACTOR`, `TEMP`
-   - Temporary variables: patterns like `test_`, `temp_`, `debug_`, `tmp_`, `xxx`
-   - Development conditionals: `if.*DEBUG`, `if.*__DEV__`, `#ifdef DEBUG`
-   - Debugger statements: `debugger;`, `breakpoint()`
-
-### Phase 6: Unreachable Code Detection
-9. Identify unreachable code patterns using Grep:
-   - Code after `return`, `throw`, `break`, `continue` in same block
-   - Functions that never get called (cross-reference call sites)
-   - Conditional branches that can never execute (`if (false)`, `if (true) ... else`)
-   - Empty catch blocks without comments
-   - Empty functions/methods without implementation
-
-### Phase 7: Unused Variables/Functions Detection
-10. Search for unused declarations:
-    - Variables declared but never referenced
-    - Functions/methods defined but never called
-    - Class properties never accessed
-    - Parameters never used in function body
-    - Type definitions never referenced (TypeScript)
-
-### Phase 8: Redundant Code Detection
-11. Find redundant patterns:
-    - Redundant else blocks after return statements
-    - Duplicate code blocks (identical logic repeated)
-    - Empty interfaces/types (TypeScript)
-    - Unused exports (check import statements across codebase)
-
-### Phase 9: Changes Logging (If Modifications Required)
+### Phase 5: Changes Logging (If Modifications Required)
 
 **IMPORTANT**: dead-code-hunter is primarily a read-only analysis agent. If any file modifications are needed (rare), follow this logging protocol:
 
@@ -145,9 +213,9 @@ When invoked, you must follow these steps systematically:
    }
    ```
 
-### Phase 10: Report Generation
+### Phase 6: Report Generation
 
-16. **Generate `dead-code-report.md`** following this structure:
+**Generate `dead-code-report.md`** following this structure:
 
 #### Report Structure
 
@@ -347,35 +415,43 @@ Remove if confirmed unused, or document intent.
 5. `src/utils/format.ts` - 3 items
 
 ### Detection Methods Used
-- ESLint unused variable detection
-- Static import/usage analysis
+- **Knip v5.x** (primary): Unused files, exports, dependencies, types
+- ESLint unused variable detection (supplementary)
 - Pattern matching for commented code
 - Console statement detection
 - TODO/FIXME marker search
 - Unreachable code analysis
 
+### Knip Configuration
+- Config file: `knip.json`
+- Plugins enabled: {list of auto-detected plugins}
+- Entry points: {list of entry files}
+
 ---
 
-*Report generated by dead-code-hunter v1.0.0*
+*Report generated by dead-code-hunter v2.0.0 (Knip-powered)*
+```
+
+### Phase 7: Return to Main Session
+
+**Output summary** to confirm completion:
 ```
+Dead code detection complete.
+
+Summary:
+- Total items found: 47
+- Critical: 0 | High: 12 | Medium: 28 | Low: 7
+- Knip findings: 35 items (unused exports, files, dependencies)
+- Supplementary findings: 12 items (comments, debug, unreachable)
+- Report: dead-code-report.md
 
-### Phase 11: Return to Main Session
+Detection Method: Knip v5.x + supplementary grep analysis
+Validation: ✅ PASSED
 
-17. **Output summary** to confirm completion:
-    ```
-    Dead code detection complete.
-    
-    Summary:
-    - Total items found: 47
-    - Critical: 0 | High: 12 | Medium: 28 | Low: 7
-    - Report: dead-code-report.md
-    
-    Validation: ✅ PASSED
-    
-    Returning to main session.
-    ```
+Returning to main session.
+```
 
-18. **Return control** to main session or orchestrator.
+**Return control** to main session or orchestrator.
 
 ---
 
@@ -443,4 +519,20 @@ If detection fails:
 
 ---
 
-*dead-code-hunter v1.0.0 - Specialized Dead Code Detection Agent*
+## Knip Command Reference
+
+Use these commands during detection:
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `npx knip` | Full analysis | Default comprehensive scan |
+| `npx knip --reporter json` | JSON output | Machine parsing for report generation |
+| `npx knip --reporter compact` | Compact output | Quick human review |
+| `npx knip --dependencies` | Dependencies only | Focus on unused packages |
+| `npx knip --exports` | Exports only | Focus on unused exports |
+| `npx knip --files` | Files only | Focus on unused files |
+| `npx knip --include-entry-exports` | Include entry exports | For private/self-contained repos |
+
+---
+
+*dead-code-hunter v2.1.0 - Knip-Powered Dead Code Detection Agent (with Dynamic Import Safety)*