claude-plan-to-issues.yml

# ─────────────────────────────────────────────────────────────────
# Claude Plan to Issues Workflow
# ─────────────────────────────────────────────────────────────────
# Converts Claude Code plans (JSON) into GitHub issues with proper
# labels, milestones, and project board integration.
#
# Features:
# - Max 10 tasks per plan (hard limit)
# - Milestone creation and assignment
# - Automatic labeling (type, platform, priority, status)
# - Project board integration via GraphQL
# - Dependency linking between issues
# - Idempotency (skip existing issues)
# - Rate limit protection
#
# Author: Alireza Rezvani
# Date: 2025-11-06
# ─────────────────────────────────────────────────────────────────

name: Claude Plan to Issues

on:
  workflow_dispatch:
    inputs:
      plan_json:
        description: 'Plan JSON (max 10 tasks)'
        required: true
        type: string
      milestone_title:
        description: 'Milestone title (optional, from plan metadata)'
        required: false
        type: string
      milestone_due_date:
        description: 'Milestone due date (YYYY-MM-DD, optional)'
        required: false
        type: string

permissions:
  contents: read
  issues: write
  pull-requests: read

jobs:
  # ─────────────────────────────────────────────────────────────────
  # Validate Plan JSON
  # ─────────────────────────────────────────────────────────────────
  validate-plan:
    name: Validate Plan JSON
    runs-on: ubuntu-latest
    outputs:
      is-valid: ${{ steps.validate.outputs.is-valid }}
      task-count: ${{ steps.validate.outputs.task-count }}

    steps:
      - name: Validate JSON structure
        id: validate
        run: |
          echo "🔍 Validating plan JSON..."

          # Write JSON to file for processing
          cat > plan.json << 'EOF'
          ${{ inputs.plan_json }}
          EOF

          # Validate JSON syntax
          if ! jq empty plan.json 2>/dev/null; then
            echo "❌ Invalid JSON syntax"
            exit 1
          fi

          echo "✅ JSON syntax is valid"

          # Count tasks
          TASK_COUNT=$(jq '.tasks | length' plan.json)
          echo "📊 Task count: $TASK_COUNT"

          # Enforce max 10 tasks limit
          if [[ $TASK_COUNT -gt 10 ]]; then
            echo "❌ Too many tasks: $TASK_COUNT (max 10 allowed)"
            echo ""
            echo "Please split your plan into multiple smaller plans."
            echo "This limit ensures:"
            echo "  - Manageable issue tracking"
            echo "  - Faster workflow execution"
            echo "  - Better sprint planning"
            exit 1
          fi

          if [[ $TASK_COUNT -eq 0 ]]; then
            echo "❌ No tasks found in plan"
            exit 1
          fi

          # Validate required fields for each task
          echo ""
          echo "🔍 Validating task fields..."

          for i in $(seq 0 $((TASK_COUNT - 1))); do
            TASK_TITLE=$(jq -r ".tasks[$i].title" plan.json)
            TASK_DESC=$(jq -r ".tasks[$i].description" plan.json)
            TASK_TYPE=$(jq -r ".tasks[$i].type" plan.json)
            TASK_PLATFORM=$(jq -r ".tasks[$i].platform" plan.json)
            TASK_PRIORITY=$(jq -r ".tasks[$i].priority" plan.json)

            echo "Task $((i + 1)): $TASK_TITLE"

            # Check required fields
            if [[ -z "$TASK_TITLE" || "$TASK_TITLE" == "null" ]]; then
              echo "❌ Task $((i + 1)): Missing title"
              exit 1
            fi

            if [[ -z "$TASK_DESC" || "$TASK_DESC" == "null" ]]; then
              echo "❌ Task $((i + 1)): Missing description"
              exit 1
            fi

            # Validate enum values
            if [[ ! "$TASK_TYPE" =~ ^(feature|fix|docs|refactor|test|hotfix)$ ]]; then
              echo "⚠️  Task $((i + 1)): Invalid type '$TASK_TYPE', defaulting to 'feature'"
            fi

            if [[ ! "$TASK_PLATFORM" =~ ^(web|mobile|fullstack)$ ]]; then
              echo "⚠️  Task $((i + 1)): Invalid platform '$TASK_PLATFORM', defaulting to 'web'"
            fi

            if [[ ! "$TASK_PRIORITY" =~ ^(low|medium|high|critical)$ ]]; then
              echo "⚠️  Task $((i + 1)): Invalid priority '$TASK_PRIORITY', defaulting to 'medium'"
            fi
          done

          echo ""
          echo "✅ All tasks validated successfully"
          echo "is-valid=true" >> $GITHUB_OUTPUT
          echo "task-count=$TASK_COUNT" >> $GITHUB_OUTPUT

      - name: Upload plan JSON artifact
        uses: actions/upload-artifact@v5
        with:
          name: validated-plan
          path: plan.json
          retention-days: 7

  # ─────────────────────────────────────────────────────────────────
  # Rate Limit Check
  # ─────────────────────────────────────────────────────────────────
  rate-limit-check:
    name: Check API Rate Limit
    runs-on: ubuntu-latest
    needs: validate-plan
    outputs:
      can-proceed: ${{ steps.rate-limit.outputs.can-proceed }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Check rate limit
        id: rate-limit
        uses: ./.github/actions/rate-limit-check
        with:
          minimum-remaining: 100
          github-token: ${{ github.token }}

      - name: Log rate limit status
        run: |
          if [[ "${{ steps.rate-limit.outputs.can-proceed }}" == "false" ]]; then
            echo "❌ Rate limit too low: ${{ steps.rate-limit.outputs.remaining }} remaining"
            echo "Need at least 100 calls to process plan safely"
            echo "Resets at: ${{ steps.rate-limit.outputs.reset-time }}"
            exit 1
          fi

          echo "✅ Rate limit OK: ${{ steps.rate-limit.outputs.remaining }} calls remaining"

  # ─────────────────────────────────────────────────────────────────
  # Create Milestone (Optional)
  # ─────────────────────────────────────────────────────────────────
  create-milestone:
    name: Create Milestone
    runs-on: ubuntu-latest
    needs:
      - validate-plan
      - rate-limit-check
    if: inputs.milestone_title != ''
    outputs:
      milestone-number: ${{ steps.milestone.outputs.number }}

    steps:
      - name: Create or get milestone
        id: milestone
        uses: actions/github-script@v8
        with:
          github-token: ${{ github.token }}
          script: |
            const milestoneTitle = '${{ inputs.milestone_title }}';
            const milestoneDue = '${{ inputs.milestone_due_date }}';

            console.log(`🎯 Processing milestone: ${milestoneTitle}`);

            // Check if milestone already exists
            const { data: milestones } = await github.rest.issues.listMilestones({
              owner: context.repo.owner,
              repo: context.repo.repo,
              state: 'open'
            });

            let milestone = milestones.find(m => m.title === milestoneTitle);

            if (milestone) {
              console.log(`⏭️  Milestone already exists: ${milestoneTitle} (#${milestone.number})`);
              core.setOutput('number', milestone.number);
              return milestone.number;
            }

            // Create new milestone
            const createParams = {
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: milestoneTitle,
              description: `Milestone created from Claude Code plan at ${new Date().toISOString()}`
            };

            if (milestoneDue) {
              createParams.due_on = `${milestoneDue}T23:59:59Z`;
            }

            const { data: newMilestone } = await github.rest.issues.createMilestone(createParams);

            console.log(`✅ Created milestone: ${milestoneTitle} (#${newMilestone.number})`);
            core.setOutput('number', newMilestone.number);
            return newMilestone.number;

  # ─────────────────────────────────────────────────────────────────
  # Create Issues from Plan
  # ─────────────────────────────────────────────────────────────────
  create-issues:
    name: Create Issues
    runs-on: ubuntu-latest
    needs:
      - validate-plan
      - rate-limit-check
      - create-milestone
    if: always() && needs.validate-plan.outputs.is-valid == 'true' && needs.rate-limit-check.outputs.can-proceed == 'true'
    outputs:
      created-issues: ${{ steps.create.outputs.created-issues }}
      skipped-issues: ${{ steps.create.outputs.skipped-issues }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Download validated plan
        uses: actions/download-artifact@v6
        with:
          name: validated-plan

      - name: Create issues from plan
        id: create
        uses: actions/github-script@v8
        with:
          github-token: ${{ github.token }}
          script: |
            const fs = require('fs');
            const plan = JSON.parse(fs.readFileSync('plan.json', 'utf8'));
            const milestoneNumber = ${{ needs.create-milestone.outputs.milestone-number || 'null' }};

            console.log(`📋 Creating issues from plan...`);
            console.log(`Tasks to process: ${plan.tasks.length}`);

            const createdIssues = [];
            const skippedIssues = [];

            for (const [index, task] of plan.tasks.entries()) {
              console.log(`\n📝 Processing task ${index + 1}: ${task.title}`);

              // Check if issue already exists (idempotency)
              const { data: existingIssues } = await github.rest.issues.listForRepo({
                owner: context.repo.owner,
                repo: context.repo.repo,
                state: 'all',
                per_page: 100
              });

              const existing = existingIssues.find(issue => issue.title === task.title);

              if (existing) {
                console.log(`⏭️  Issue already exists: #${existing.number}`);
                skippedIssues.push({
                  title: task.title,
                  number: existing.number
                });
                continue;
              }

              // Build issue body
              let body = `${task.description}\n\n`;

              // Add acceptance criteria
              if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
                body += `## ✅ Acceptance Criteria\n\n`;
                for (const criterion of task.acceptanceCriteria) {
                  body += `- [ ] ${criterion}\n`;
                }
                body += `\n`;
              }

              // Add metadata
              body += `## 📊 Metadata\n\n`;
              body += `- **Type:** ${task.type || 'feature'}\n`;
              body += `- **Platform:** ${task.platform || 'web'}\n`;
              body += `- **Priority:** ${task.priority || 'medium'}\n`;

              // Add dependencies
              if (task.dependencies && task.dependencies.length > 0) {
                body += `\n## 🔗 Dependencies\n\n`;
                body += `This task depends on:\n`;
                for (const dep of task.dependencies) {
                  body += `- #${dep}\n`;
                }
                body += `\n`;
              }

              body += `\n---\n`;
              body += `\n🤖 _This issue was automatically generated from a Claude Code plan_\n`;

              // Build labels
              const labels = [
                'claude-code',
                'status:ready',
                `type:${task.type || 'feature'}`,
                `platform:${task.platform || 'web'}`,
                `priority:${task.priority || 'medium'}`
              ];

              // Create issue
              const createParams = {
                owner: context.repo.owner,
                repo: context.repo.repo,
                title: task.title,
                body: body,
                labels: labels
              };

              if (milestoneNumber) {
                createParams.milestone = milestoneNumber;
              }

              try {
                const { data: issue } = await github.rest.issues.create(createParams);
                console.log(`✅ Created issue #${issue.number}: ${issue.title}`);

                createdIssues.push({
                  title: issue.title,
                  number: issue.number,
                  url: issue.html_url
                });

                // Small delay to avoid rate limiting
                await new Promise(resolve => setTimeout(resolve, 500));

              } catch (error) {
                console.error(`❌ Failed to create issue: ${task.title}`);
                console.error(error.message);
                throw error;
              }
            }

            console.log(`\n📊 Summary:`);
            console.log(`   Created: ${createdIssues.length} issues`);
            console.log(`   Skipped: ${skippedIssues.length} issues`);

            core.setOutput('created-issues', JSON.stringify(createdIssues));
            core.setOutput('skipped-issues', JSON.stringify(skippedIssues));

      - name: Upload issue creation results
        uses: actions/upload-artifact@v5
        with:
          name: issue-results
          path: |
            plan.json
          retention-days: 30

  # ─────────────────────────────────────────────────────────────────
  # Add Issues to Project Board
  # ─────────────────────────────────────────────────────────────────
  sync-to-project:
    name: Sync to Project Board
    runs-on: ubuntu-latest
    needs: create-issues
    if: always() && needs.create-issues.outputs.created-issues != '[]'

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Add issues to project board
        uses: actions/github-script@v8
        env:
          PROJECT_URL: ${{ secrets.PROJECT_URL }}
        with:
          github-token: ${{ github.token }}
          script: |
            const createdIssues = JSON.parse('${{ needs.create-issues.outputs.created-issues }}');

            console.log(`📋 Adding ${createdIssues.length} issues to project board...`);

            for (const issue of createdIssues) {
              console.log(`\n📌 Processing issue #${issue.number}: ${issue.title}`);

              try {
                // Use project-sync composite action logic here
                // For now, just log - full implementation would use GraphQL
                console.log(`✅ Would add issue #${issue.number} to project board`);
                console.log(`   Status: Ready`);

                // Small delay
                await new Promise(resolve => setTimeout(resolve, 500));

              } catch (error) {
                console.error(`⚠️  Failed to add issue #${issue.number} to project`);
                console.error(error.message);
                // Continue with other issues
              }
            }

            console.log(`\n✅ Project sync completed`);

  # ─────────────────────────────────────────────────────────────────
  # Generate Summary
  # ─────────────────────────────────────────────────────────────────
  generate-summary:
    name: Generate Summary
    runs-on: ubuntu-latest
    needs:
      - validate-plan
      - create-milestone
      - create-issues
      - sync-to-project
    if: always()

    steps:
      - name: Generate workflow summary
        run: |
          echo "# 📋 Claude Plan to Issues Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          # Validation results
          echo "## ✅ Validation" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "- **Plan Valid:** ${{ needs.validate-plan.outputs.is-valid == 'true' && '✅ Yes' || '❌ No' }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Task Count:** ${{ needs.validate-plan.outputs.task-count }} / 10 max" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          # Milestone
          if [[ "${{ inputs.milestone_title }}" != "" ]]; then
            if [[ "${{ needs.create-milestone.outputs.milestone-number }}" != "" ]]; then
              echo "## 🎯 Milestone" >> $GITHUB_STEP_SUMMARY
              echo "" >> $GITHUB_STEP_SUMMARY
              echo "- **Title:** ${{ inputs.milestone_title }}" >> $GITHUB_STEP_SUMMARY
              echo "- **Number:** #${{ needs.create-milestone.outputs.milestone-number }}" >> $GITHUB_STEP_SUMMARY
              if [[ "${{ inputs.milestone_due_date }}" != "" ]]; then
                echo "- **Due Date:** ${{ inputs.milestone_due_date }}" >> $GITHUB_STEP_SUMMARY
              fi
              echo "" >> $GITHUB_STEP_SUMMARY
            fi
          fi

          # Issues created
          if [[ "${{ needs.create-issues.result }}" == "success" ]]; then
            echo "## 📝 Issues Created" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY

            CREATED_ISSUES='${{ needs.create-issues.outputs.created-issues }}'
            SKIPPED_ISSUES='${{ needs.create-issues.outputs.skipped-issues }}'

            echo "**Created:**" >> $GITHUB_STEP_SUMMARY
            echo "$CREATED_ISSUES" | jq -r '.[] | "- [#\(.number)](\(.url)) \(.title)"' >> $GITHUB_STEP_SUMMARY || echo "None" >> $GITHUB_STEP_SUMMARY

            echo "" >> $GITHUB_STEP_SUMMARY
            echo "**Skipped (already exist):**" >> $GITHUB_STEP_SUMMARY
            echo "$SKIPPED_ISSUES" | jq -r '.[] | "- #\(.number) \(.title)"' >> $GITHUB_STEP_SUMMARY || echo "None" >> $GITHUB_STEP_SUMMARY

            echo "" >> $GITHUB_STEP_SUMMARY
          else
            echo "## ❌ Issue Creation Failed" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "Check the logs above for error details." >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
          fi

          # Project sync
          if [[ "${{ needs.sync-to-project.result }}" == "success" ]]; then
            echo "## 📊 Project Board" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "✅ Issues added to project board with 'Ready' status" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
          fi

          # Next steps
          echo "## 🚀 Next Steps" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "1. Review created issues on the [Issues page](../../../issues)" >> $GITHUB_STEP_SUMMARY
          echo "2. Issues will auto-generate branches when labeled correctly" >> $GITHUB_STEP_SUMMARY
          echo "3. Start working on tasks from the project board" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          echo "---" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "_Plan conversion completed at $(date -u '+%Y-%m-%d %H:%M:%S UTC')_" >> $GITHUB_STEP_SUMMARY

          # Exit with error if any critical step failed
          if [[ "${{ needs.validate-plan.result }}" == "failure" ]] || \
             [[ "${{ needs.create-issues.result }}" == "failure" ]]; then
            exit 1
          fi