claude-code-orchestrator-kit 1.0.0

package/.github/workflows/test.yml

@@ -0,0 +1,104 @@
+name: Test
+
+on:
+  push:
+    branches: ['**']
+  pull_request:
+    branches: ['**']
+
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    strategy:
+      matrix:
+        node-version: [20.x]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8.15.0
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Clean TypeScript build cache
+        run: find . -name "*.tsbuildinfo" -type f -delete
+
+      - name: Run linting
+        run: pnpm lint
+
+      - name: Run type checking
+        run: pnpm type-check
+
+      - name: Run Vitest tests
+        run: pnpm test
+        env:
+          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
+          SUPABASE_SERVICE_KEY: ${{ secrets.SUPABASE_SERVICE_KEY }}
+          SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
+          QDRANT_URL: ${{ secrets.QDRANT_URL }}
+          QDRANT_API_KEY: ${{ secrets.QDRANT_API_KEY }}
+          JINA_API_KEY: ${{ secrets.JINA_API_KEY }}
+          UPSTASH_REDIS_URL: ${{ secrets.UPSTASH_REDIS_URL }}
+          UPSTASH_REDIS_TOKEN: ${{ secrets.UPSTASH_REDIS_TOKEN }}
+
+      - name: Setup Supabase CLI
+        uses: supabase/setup-cli@v1
+        with:
+          version: latest
+
+      - name: Start Supabase local instance
+        run: |
+          cd packages/course-gen-platform
+          supabase start
+
+      - name: Run pgTAP/RLS tests
+        run: pnpm test:rls
+        env:
+          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
+          SUPABASE_SERVICE_KEY: ${{ secrets.SUPABASE_SERVICE_KEY }}
+          SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
+
+      - name: Stop Supabase
+        if: always()
+        run: |
+          cd packages/course-gen-platform
+          supabase stop
+
+      - name: Upload test coverage
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-coverage
+          path: |
+            packages/**/coverage/
+            **/coverage/
+          retention-days: 7
+          if-no-files-found: warn

package/.gitignore

@@ -0,0 +1,116 @@
+# ===================================================================
+# Claude Code Orchestrator Kit - .gitignore
+# ===================================================================
+
+# ===================================================================
+# Sensitive Files - NEVER COMMIT THESE
+# ===================================================================
+# Environment files with credentials
+.env.local
+.env.*.local
+*.env.local
+
+# MCP local configuration (may contain secrets)
+.mcp.local.json
+
+# Local settings
+.claude/settings.local.json
+
+# ===================================================================
+# Temporary Files
+# ===================================================================
+# Claude Code temporary files
+.tmp/
+*.tmp
+.cache/
+
+# Logs
+*.log
+logs/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# ===================================================================
+# Dependencies
+# ===================================================================
+node_modules/
+.pnp
+.pnp.js
+
+# ===================================================================
+# Build & Distribution
+# ===================================================================
+dist/
+build/
+out/
+.next/
+.nuxt/
+.vercel/
+
+# ===================================================================
+# Testing
+# ===================================================================
+coverage/
+.nyc_output/
+*.lcov
+
+# ===================================================================
+# OS Files
+# ===================================================================
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# Linux
+*~
+.directory
+.Trash-*
+
+# ===================================================================
+# IDE & Editors
+# ===================================================================
+# VSCode
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+
+# JetBrains
+.idea/
+*.iml
+*.iws
+*.ipr
+
+# Vim
+*.swp
+*.swo
+*~
+
+# ===================================================================
+# Project Specific
+# ===================================================================
+# Git worktrees
+.worktrees/
+
+# Backup files
+*.backup
+*.bak
+*.old
+
+# Archive files
+*.archive
+
+# Lock files (optional - uncomment if needed)
+# package-lock.json
+# yarn.lock
+# pnpm-lock.yaml
+*.tgz

package/CLAUDE.md

@@ -0,0 +1,137 @@
+# Agent Orchestration Rules
+
+> **IMPORTANT**: This file overrides default Claude Code behavior. Follow these rules strictly.
+
+## Main Pattern: You Are The Orchestrator
+
+This is the DEFAULT pattern used in 95% of cases for feature development, bug fixes, refactoring, and general coding tasks.
+
+### Core Rules
+
+**1. GATHER FULL CONTEXT FIRST (MANDATORY)**
+
+Before delegating or implementing any task:
+- Read existing code in related files
+- Search codebase for similar patterns
+- Review relevant documentation (specs, design docs, ADRs)
+- Check recent commits in related areas
+- Understand dependencies and integration points
+
+NEVER delegate or implement blindly.
+
+**2. DELEGATE TO SUBAGENTS**
+
+Before delegation:
+- Provide complete context (code snippets, file paths, patterns, docs)
+- Specify exact expected output and validation criteria
+
+After delegation (CRITICAL):
+- ALWAYS verify results (read modified files, run type-check)
+- NEVER skip verification
+- If incorrect: re-delegate with corrections and errors
+- If TypeScript errors: re-delegate to same agent OR typescript-types-specialist
+
+**3. EXECUTE DIRECTLY (MINIMAL ONLY)**
+
+Direct execution only for:
+- Single dependency install
+- Single-line fixes (typos, obvious bugs)
+- Simple imports
+- Minimal config changes
+
+Everything else: delegate.
+
+**4. TRACK PROGRESS**
+
+- Create todos at task start
+- Mark in_progress BEFORE starting
+- Mark completed AFTER verification only
+
+**5. COMMIT STRATEGY**
+
+Run `/push patch` after EACH completed task:
+- Mark task [X] in tasks.md
+- Add artifacts: `→ Artifacts: [file1](path), [file2](path)`
+- Update TodoWrite to completed
+- Then `/push patch`
+
+**6. EXECUTION PATTERN**
+
+```
+FOR EACH TASK:
+1. Read task description
+2. GATHER FULL CONTEXT (code + docs + patterns + history)
+3. Delegate to subagent OR execute directly (trivial only)
+4. VERIFY results (read files + run type-check) - NEVER skip
+5. Accept/reject loop (re-delegate if needed)
+6. Update TodoWrite to completed
+7. Mark task [X] in tasks.md + add artifacts
+8. Run /push patch
+9. Move to next task
+```
+
+**7. HANDLING CONTRADICTIONS**
+
+If contradictions occur:
+- Gather context, analyze project patterns
+- If truly ambiguous: ask user with specific options
+- Only ask when unable to determine best practice (rare, ~10%)
+
+### Planning Phase (ALWAYS First)
+
+Before implementing tasks:
+- Analyze execution model (parallel/sequential)
+- Assign executors: MAIN for trivial, existing if 100% match, FUTURE otherwise
+- Create FUTURE agents: launch N meta-agent-v3 calls in single message, ask restart
+- Resolve research (simple: solve now, complex: deepresearch prompt)
+- Atomicity: 1 task = 1 agent call
+- Parallel: launch N calls in single message (not sequentially)
+
+See speckit.implement.md for details.
+
+---
+
+## Health Workflows Pattern (5% of cases)
+
+Slash commands: `/health-bugs`, `/health-security`, `/health-cleanup`, `/health-deps`
+
+Follow command-specific instructions. See `docs/Agents Ecosystem/AGENT-ORCHESTRATION.md`.
+
+---
+
+## Project Conventions
+
+**File Organization**:
+- Agents: `.claude/agents/{domain}/{orchestrators|workers}/`
+- Commands: `.claude/commands/`
+- Skills: `.claude/skills/{skill-name}/SKILL.md`
+- Temporary: `.tmp/current/` (git ignored)
+- Reports: `docs/reports/{domain}/{YYYY-MM}/`
+
+**Code Standards**:
+- Type-check must pass before commit
+- Build must pass before commit
+- No hardcoded credentials
+
+**Agent Selection**:
+- Worker: Plan file specifies nextAgent (health workflows only)
+- Skill: Reusable utility, no state, <100 lines
+
+**Supabase Operations**:
+- Use Supabase MCP when `.mcp.json` includes supabase server
+- Project: MegaCampusAI (ref: `diqooqbuchsliypgwksu`)
+- Migrations: `packages/course-gen-platform/supabase/migrations/`
+
+**MCP Configuration**:
+- BASE (`.mcp.base.json`): context7 + sequential-thinking (~600 tokens)
+- FULL (`.mcp.full.json`): + supabase + playwright + n8n + shadcn (~5000 tokens)
+- Switch: `./switch-mcp.sh`
+
+---
+
+## Reference Docs
+
+- Agent orchestration: `docs/Agents Ecosystem/AGENT-ORCHESTRATION.md`
+- Architecture: `docs/Agents Ecosystem/ARCHITECTURE.md`
+- Quality gates: `docs/Agents Ecosystem/QUALITY-GATES-SPECIFICATION.md`
+- Report templates: `docs/Agents Ecosystem/REPORT-TEMPLATE-STANDARD.md`

package/LICENSE

@@ -0,0 +1,72 @@
+MIT License
+
+Copyright (c) 2025 Igor Maslennikov (https://github.com/maslennikov-ig)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================================
+
+THIRD-PARTY COMPONENTS
+
+This project includes and was inspired by the following open-source projects:
+
+SpecKit
+--------
+Source: https://github.com/github/spec-kit
+License: MIT License
+Copyright (c) GitHub, Inc.
+
+The SpecKit commands (speckit.analyze, speckit.specify, speckit.clarify,
+speckit.plan, speckit.implement, speckit.checklist, speckit.tasks,
+speckit.constitution) are adapted from GitHub's SpecKit project.
+
+================================================================================
+
+ACKNOWLEDGMENTS
+
+This project is built with and for:
+
+- Claude Code by Anthropic (https://claude.com/claude-code)
+  The official CLI for Claude that powers this entire orchestration system.
+
+- Context7 by Upstash (https://upstash.com/context7)
+  MCP server providing real-time library documentation and best practices.
+
+- Smithery Sequential Thinking (https://smithery.ai/)
+  Enhanced reasoning capabilities through structured thinking processes.
+
+- Supabase MCP Server (https://github.com/supabase/mcp-server-supabase)
+  Database access and management through Model Context Protocol.
+
+- n8n (https://n8n.io/)
+  Workflow automation platform integration.
+
+- Playwright (https://playwright.dev/)
+  Browser automation for testing and validation.
+
+- shadcn/ui (https://ui.shadcn.com/)
+  Beautiful UI component system.
+
+Special thanks to the open-source community and all contributors who make
+projects like this possible.
+
+================================================================================
+
+For questions, issues, or contributions, please visit:
+https://github.com/maslennikov-ig/claude-code-orchestrator-kit