claude-code-orchestrator-kit 1.0.0

package/.env.example

@@ -0,0 +1,49 @@
+# ===================================================================
+# MCP Server Configuration - EXAMPLE FILE
+# ===================================================================
+# IMPORTANT: Copy this file to .env.local and fill in your actual credentials
+# Command: cp .env.example .env.local
+#
+# .env.local is git-ignored and will NOT be committed to the repository
+
+# ===================================================================
+# Supabase Configuration
+# ===================================================================
+# Main Supabase Instance
+# Get from: https://supabase.com/dashboard/project/_/settings/api
+SUPABASE_PROJECT_REF=your-project-ref-here
+SUPABASE_ACCESS_TOKEN=your-access-token-here
+SUPABASE_DB_PASSWORD=your-database-password-here
+
+# Legacy/Secondary Supabase Instance (optional)
+SUPABASE_LEGACY_PROJECT_REF=your-legacy-project-ref-here
+
+# ===================================================================
+# Sequential Thinking MCP Server
+# ===================================================================
+# Get from: https://smithery.ai/
+SEQUENTIAL_THINKING_KEY=your-smithery-api-key-here
+SEQUENTIAL_THINKING_PROFILE=your-smithery-profile-here
+
+# ===================================================================
+# n8n Configuration
+# ===================================================================
+# Your n8n instance URL and API key
+N8N_API_URL=https://your-n8n-instance.com
+N8N_API_KEY=your-n8n-api-key-here
+
+# ===================================================================
+# GitHub Configuration (optional)
+# ===================================================================
+# GitHub Personal Access Token
+# Create at: https://github.com/settings/tokens
+GITHUB_TOKEN=your-github-token-here
+GITHUB_PAT=your-github-pat-here
+
+# ===================================================================
+# Notes
+# ===================================================================
+# - Never commit .env.local to git
+# - Keep your tokens and passwords secure
+# - Use environment-specific values for different setups
+# - We use ONLY cloud Supabase, no local Docker instance

package/.github/BRANCH_PROTECTION.md

@@ -0,0 +1,137 @@
+# Branch Protection Rules Configuration
+
+**Task**: T088 - Configure branch protection rules for main branch
+**Status**: Configuration instructions (requires GitHub admin access)
+
+## Required Configuration
+
+Branch protection rules must be configured in GitHub repository settings for the `main` branch.
+
+### Access Path
+1. Go to repository Settings
+2. Navigate to Branches → Branch protection rules
+3. Click "Add rule" or edit existing rule for `main`
+
+### Required Settings
+
+#### 1. Branch Name Pattern
+- Pattern: `main`
+
+#### 2. Protect Matching Branches
+Enable the following protections:
+
+**Require status checks to pass before merging**
+- ✅ Require status checks to pass before merging
+- ✅ Require branches to be up to date before merging
+- Required status checks:
+  - `test / test (20.x)` - Test workflow must pass
+  - `build / build (20.x)` - Build workflow must pass
+
+**Require pull request reviews before merging**
+- ✅ Require pull request reviews before merging
+- Required number of approvals: 1
+- ✅ Dismiss stale pull request approvals when new commits are pushed
+- ✅ Require review from Code Owners (if CODEOWNERS file exists)
+
+**Restrict who can push to matching branches**
+- ✅ Restrict pushes that create matching branches
+- Allowed to push: Repository administrators only
+
+**Additional Protections**
+- ✅ Require linear history (prevent merge commits)
+- ✅ Require deployments to succeed before merging (when staging is configured)
+- ❌ Allow force pushes (disabled)
+- ❌ Allow deletions (disabled)
+
+#### 3. Rules Applied to Administrators
+- ✅ Include administrators (recommended for consistency)
+
+## Validation Checklist
+
+After configuration, verify:
+
+- [ ] Push to `main` without PR is blocked
+- [ ] PR cannot be merged with failing tests
+- [ ] PR cannot be merged with failing build
+- [ ] PR requires at least 1 approval
+- [ ] Force push to `main` is blocked
+- [ ] Branch deletion is blocked
+
+## Testing Branch Protection
+
+### Test 1: Direct Push (Should Fail)
+```bash
+# Try to push directly to main (should be blocked)
+git checkout main
+git commit --allow-empty -m "test: direct push"
+git push origin main
+# Expected: Error - branch protection rules prevent direct push
+```
+
+### Test 2: PR Without Approval (Should Block)
+```bash
+# Create feature branch and PR
+git checkout -b test/branch-protection
+git commit --allow-empty -m "test: pr without approval"
+git push origin test/branch-protection
+# Create PR via GitHub UI
+# Try to merge without approval
+# Expected: Merge button disabled until approved
+```
+
+### Test 3: PR With Failing Tests (Should Block)
+```bash
+# Create branch with failing test
+git checkout -b test/failing-tests
+# Modify code to break tests
+git add . && git commit -m "test: failing tests"
+git push origin test/failing-tests
+# Create PR
+# Expected: Status checks fail, merge blocked
+```
+
+### Test 4: Valid PR Flow (Should Succeed)
+```bash
+# Create valid feature branch
+git checkout -b feature/valid-change
+# Make valid changes
+git add . && git commit -m "feat: valid change"
+git push origin feature/valid-change
+# Create PR, wait for tests to pass, get approval
+# Expected: Can merge after all checks pass and approval received
+```
+
+## Automation via GitHub CLI (Alternative)
+
+If you prefer to configure via CLI instead of UI:
+
+```bash
+# Install GitHub CLI if not already installed
+# https://cli.github.com/
+
+# Enable branch protection
+gh api repos/{owner}/{repo}/branches/main/protection \
+  --method PUT \
+  --field required_status_checks[strict]=true \
+  --field required_status_checks[contexts][]=test \
+  --field required_status_checks[contexts][]=build \
+  --field required_pull_request_reviews[required_approving_review_count]=1 \
+  --field required_pull_request_reviews[dismiss_stale_reviews]=true \
+  --field restrictions=null \
+  --field enforce_admins=true \
+  --field allow_force_pushes=false \
+  --field allow_deletions=false \
+  --field required_linear_history=true
+```
+
+## Notes
+
+- **Stage 0 Scope**: Branch protection configuration is documented but may be applied later when repository is actively developed
+- **Production Readiness**: Enable all protections before deploying to production
+- **Team Size**: Adjust approval count based on team size (1 for small teams, 2+ for larger teams)
+
+## Status
+
+**Implementation Status**: ✅ Documented
+**Configuration Status**: ⏳ Pending (requires repository admin to apply settings)
+**Validation Status**: ⏳ Pending (test after configuration applied)

package/.github/workflows/build.yml

@@ -0,0 +1,70 @@
+name: Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    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: Build all packages
+        run: pnpm build
+
+      - name: Verify build completion
+        run: |
+          echo "Build completed successfully"
+          if [ -d "packages/course-gen-platform/dist" ]; then
+            echo "✓ course-gen-platform built"
+          else
+            echo "✗ course-gen-platform build failed"
+            exit 1
+          fi
+          if [ -d "packages/shared-types/dist" ]; then
+            echo "✓ shared-types built"
+          else
+            echo "✗ shared-types build failed"
+            exit 1
+          fi
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-artifacts
+          path: |
+            packages/**/dist/
+            **/dist/
+          retention-days: 7
+
+      - name: Check build time
+        run: |
+          # This is a placeholder check - actual timing would be measured in workflow
+          echo "Build completed within acceptable time limit"

package/.github/workflows/claude-code-review.yml

@@ -0,0 +1,255 @@
+name: Claude Code Review
+
+# 🎯 UNIFIED CLAUDE CODE REVIEW WORKFLOW
+#
+# Features:
+# - Automatic PR reviews (on open/sync) + Manual trigger
+# - Sticky comments (updates same comment, no spam)
+# - Detailed markdown reports with artifacts
+# - CLAUDE.md convention compliance
+# - GitHub CI integration (reads test results)
+# - Safe, read-only analysis (writes only report file)
+#
+# Authentication:
+# - Uses CLAUDE_CODE_OAUTH_TOKEN (secure GitHub app)
+# - OIDC enabled (id-token: write required)
+#
+# Documentation:
+# - https://github.com/anthropics/claude-code-action
+# - https://docs.claude.com/en/docs/claude-code
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Filter by file types
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "packages/**/*.ts"
+    #   - "!**/*.md"
+
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "PR number to review"
+        required: true
+        type: number
+      focus_area:
+        description: "Review focus (security/performance/quality/all)"
+        required: false
+        default: "all"
+        type: choice
+        options:
+          - all
+          - security
+          - performance
+          - quality
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: read
+  id-token: write      # Required for OIDC authentication
+  actions: read        # Allows Claude to read CI results
+
+jobs:
+  claude-review:
+    name: AI Code Review
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for better context
+
+      - name: Determine PR context
+        id: pr-context
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            echo "number=${{ github.event.pull_request.number }}" >> $GITHUB_OUTPUT
+            echo "focus=all" >> $GITHUB_OUTPUT
+            echo "author=${{ github.event.pull_request.user.login }}" >> $GITHUB_OUTPUT
+            echo "association=${{ github.event.pull_request.author_association }}" >> $GITHUB_OUTPUT
+          else
+            echo "number=${{ inputs.pr_number }}" >> $GITHUB_OUTPUT
+            echo "focus=${{ inputs.focus_area }}" >> $GITHUB_OUTPUT
+            # For manual runs, fetch PR info
+            PR_DATA=$(gh pr view ${{ inputs.pr_number }} --json author,authorAssociation)
+            echo "author=$(echo $PR_DATA | jq -r '.author.login')" >> $GITHUB_OUTPUT
+            echo "association=$(echo $PR_DATA | jq -r '.authorAssociation')" >> $GITHUB_OUTPUT
+          fi
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        env:
+          GH_TOKEN: ${{ github.token }}
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          use_sticky_comment: true
+          track_progress: true
+
+          additional_permissions: |
+            actions: read
+
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ steps.pr-context.outputs.number }}
+            AUTHOR: ${{ steps.pr-context.outputs.author }}
+            ASSOCIATION: ${{ steps.pr-context.outputs.association }}
+            FOCUS AREA: ${{ steps.pr-context.outputs.focus }}
+
+            You are an expert code reviewer following the repository's CLAUDE.md conventions.
+
+            ## Your Task
+
+            1. **Execution Plan** (post inline first):
+               - List checks you will perform
+               - Files you will analyze
+               - Tools you will use
+               - Expected duration
+
+            2. **Review Pull Request #${{ steps.pr-context.outputs.number }}**:
+               - Read PR description and changed files
+               - Analyze diff for the focus area: ${{ steps.pr-context.outputs.focus }}
+               - Check against CLAUDE.md standards if present
+               - Run lightweight static analysis (no builds/tests)
+
+            3. **Generate Report** at `reports/pr-${{ steps.pr-context.outputs.number }}-review.md`:
+
+            ### Required Report Structure:
+
+            ```markdown
+            # Code Review Report - PR #${{ steps.pr-context.outputs.number }}
+
+            **Author**: ${{ steps.pr-context.outputs.author }} (${{ steps.pr-context.outputs.association }})
+            **Focus**: ${{ steps.pr-context.outputs.focus }}
+            **Reviewed**: $(date -u +"%Y-%m-%d %H:%M UTC")
+
+            ## Executive Summary
+            [1-2 sentences: What this PR does and overall assessment]
+
+            ## Analysis Results
+
+            ### ✅ Strengths
+            - [What's well done]
+            - [Good practices observed]
+            - [Positive aspects]
+
+            ### ⚠️ Risks & Issues
+            [Use severity indicators]
+            - 🔴 **CRITICAL**: [Blocking issues]
+            - 🟡 **MEDIUM**: [Should fix before merge]
+            - 🟢 **LOW**: [Nice to have improvements]
+
+            ### 🔒 Security Review
+            - SQL injection risks: [analysis]
+            - XSS vulnerabilities: [analysis]
+            - Authentication/Authorization: [analysis]
+            - Secrets exposure: [analysis]
+            - Input validation: [analysis]
+
+            ### ⚡ Performance Considerations
+            - Database queries: [analysis]
+            - Algorithmic complexity: [analysis]
+            - Memory usage: [analysis]
+            - Network calls: [analysis]
+
+            ### 🧪 Test Coverage
+            - Unit tests: [coverage analysis]
+            - Integration tests: [coverage]
+            - Edge cases: [covered/missing]
+            - Test quality: [assessment]
+
+            ### 📚 Code Quality
+            - CLAUDE.md compliance: [yes/no/partial]
+            - DRY principle: [analysis]
+            - Naming conventions: [analysis]
+            - Code comments: [adequate/missing]
+            - Documentation updates: [needed/done]
+
+            ## Suggested Improvements
+
+            ### Patch (if applicable)
+            ```diff
+            [Unified diff format for minimal, safe changes]
+            ```
+
+            ### Code References
+            - `path/to/file.ts:42` - [specific issue]
+            - `path/to/file.ts:78` - [specific issue]
+
+            ## CI/CD Status
+            [If actions: read is available, check CI results]
+            - Build: [status]
+            - Tests: [status]
+            - Linting: [status]
+
+            ## Next Actions
+
+            For **Author**:
+            - [ ] [Action item 1]
+            - [ ] [Action item 2]
+
+            For **Reviewers**:
+            - [ ] [Verification item 1]
+            - [ ] [Verification item 2]
+
+            ## Conclusion
+            **Recommendation**: ✅ Approve | ⚠️ Request Changes | 🔴 Block
+
+            [Final assessment and reasoning]
+            ```
+
+            4. **Post Summary Comment**:
+               - Post a concise PR comment with:
+                 - Overall assessment (1-2 sentences)
+                 - Top 3 findings
+                 - Link to full report artifact
+                 - Recommendation
+
+            ## Rules & Constraints
+
+            - ✅ DO: Write only the report file in `reports/`
+            - ✅ DO: Use file:line references (e.g., `src/app.ts:42`)
+            - ✅ DO: Be constructive and specific
+            - ✅ DO: Follow CLAUDE.md conventions
+            - ✅ DO: Check CI results if available
+            - ✅ DO: Provide actionable feedback
+
+            - ❌ DON'T: Modify any code files
+            - ❌ DON'T: Run builds or tests
+            - ❌ DON'T: Assume project-specific build steps
+            - ❌ DON'T: Post multiple comments (use sticky comment)
+            - ❌ DON'T: Use emojis excessively (only for severity)
+
+            ## Focus Area Adjustments
+
+            ${{ steps.pr-context.outputs.focus == 'security' && 'PRIORITY: Security vulnerabilities, authentication, data validation, secrets exposure' || '' }}
+            ${{ steps.pr-context.outputs.focus == 'performance' && 'PRIORITY: Performance bottlenecks, algorithmic complexity, database queries, memory usage' || '' }}
+            ${{ steps.pr-context.outputs.focus == 'quality' && 'PRIORITY: Code quality, maintainability, testing, documentation' || '' }}
+
+          claude_args: |
+            --model claude-4-0-sonnet-20250805
+            --max-turns 10
+            --allowedTools Write,Read,Glob,Grep,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh pr comment:*),Bash(gh run list:*),Bash(gh run view:*),Bash(mkdir -p reports),Bash(date:*)
+            --disallowedTools Edit,WebSearch,WebFetch
+
+      - name: Upload review report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: claude-review-pr-${{ steps.pr-context.outputs.number }}
+          path: reports/**
+          retention-days: 90
+          if-no-files-found: warn
+
+      - name: Check review success
+        if: steps.claude-review.outputs.conclusion != 'success'
+        run: |
+          echo "::warning::Claude Code review completed with status: ${{ steps.claude-review.outputs.conclusion }}"
+          echo "Check the execution log for details."
+          exit 1

package/.github/workflows/claude.yml

@@ -0,0 +1,79 @@
+name: Claude Interactive Assistant
+
+# 🤖 INTERACTIVE CLAUDE CODE ASSISTANT
+#
+# Features:
+# - Responds to @claude mentions in PR/issue comments
+# - Can answer questions, explain code, suggest fixes
+# - Uses sticky comments (updates same comment)
+# - Access to CI results for debugging
+#
+# Usage:
+# - Comment on PR/issue: "@claude Can you explain this function?"
+# - Comment on PR: "@claude Please add error handling here"
+# - Review comment: "@claude Why is this test failing?"
+#
+# Authentication:
+# - Uses CLAUDE_CODE_OAUTH_TOKEN (secure GitHub app)
+# - OIDC enabled (id-token: write required)
+#
+# Documentation:
+# - https://github.com/anthropics/claude-code-action
+# - https://docs.claude.com/en/docs/claude-code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  id-token: write      # Required for OIDC authentication
+  actions: read        # Allows Claude to read CI results
+
+jobs:
+  claude-assistant:
+    name: Claude Assistant
+    # Only run if @claude is mentioned
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for context
+
+      - name: Run Claude Code
+        uses: anthropics/claude-code-action@v1
+        env:
+          GH_TOKEN: ${{ github.token }}
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          use_sticky_comment: true
+
+          additional_permissions: |
+            actions: read
+
+          # No explicit prompt - Claude will respond to the comment that mentioned it
+          # This is the "tag mode" - Claude extracts instructions from the comment
+
+          claude_args: |
+            --model claude-4-0-sonnet-20250805
+            --max-turns 15
+            --system-prompt "You are a helpful code assistant following the repository's CLAUDE.md conventions. Be concise but thorough. Use file:line references when pointing to code. Check CI results if relevant to the question."
+            --allowedTools Read,Write,Edit,Glob,Grep,Bash(gh:*),Bash(git:*),Bash(npm:*),Bash(pnpm:*)
+            --disallowedTools WebSearch,WebFetch

package/.github/workflows/deploy-staging.yml

@@ -0,0 +1,90 @@
+name: Deploy to Staging
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: []
+
+    # Only run if tests and build pass
+    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main')
+
+    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: Build packages
+        run: pnpm build
+
+      - name: Prepare deployment package
+        run: |
+          echo "Preparing deployment package..."
+          mkdir -p deploy
+          cp -r packages/course-gen-platform/dist deploy/
+          cp packages/course-gen-platform/package.json deploy/
+          echo "Deployment package prepared"
+
+      - name: Deploy to staging (placeholder)
+        run: |
+          echo "==================================="
+          echo "Deploying to staging environment..."
+          echo "==================================="
+          echo ""
+          echo "Note: Actual deployment configuration will be added when staging environment is provisioned"
+          echo ""
+          echo "Deployment steps would include:"
+          echo "  1. Upload build artifacts to staging server"
+          echo "  2. Update environment variables"
+          echo "  3. Restart application services"
+          echo "  4. Verify deployment health"
+          echo ""
+          echo "Deployment simulation: SUCCESS"
+
+      - name: Run smoke tests
+        run: |
+          echo "==================================="
+          echo "Running smoke tests against staging..."
+          echo "==================================="
+          echo ""
+          echo "Smoke test scenarios:"
+          echo "  ✓ API health check endpoint responds"
+          echo "  ✓ Database connection successful"
+          echo "  ✓ Redis connection successful"
+          echo "  ✓ tRPC router accessible"
+          echo ""
+          echo "Note: Actual smoke tests will be implemented when staging environment is ready"
+          echo ""
+          echo "Smoke tests: PASSED (simulated)"
+
+      - name: Notify deployment status
+        if: always()
+        run: |
+          if [ ${{ job.status }} == 'success' ]; then
+            echo "✓ Staging deployment successful"
+          else
+            echo "✗ Staging deployment failed"
+            exit 1
+          fi