ai-enhancement-guide.yml

name: Enhancement Guide

on:
  issues:
    types: [opened, labeled]

concurrency:
  group: enhancement-guide-${{ github.event.issue.number }}
  cancel-in-progress: true

permissions:
  issues: write
  contents: read

jobs:
  guide:
    # On 'opened': run if issue has 'enhancement' label
    # On 'labeled': run only if the label just added is 'enhancement'
    if: >-
      (github.event.action == 'opened' && contains(github.event.issue.labels.*.name, 'enhancement'))
      || (github.event.action == 'labeled' && github.event.label.name == 'enhancement')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1

      - name: Get issue details
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh issue view ${{ github.event.issue.number }} \
            --repo ${{ github.repository }} \
            --json title,body,labels > /tmp/issue.json

      - name: Gather project context
        run: |
          # Architecture and key concepts
          cat CLAUDE.md > /tmp/claude-md.txt

          # MDL quick reference (all current syntax)
          if [ -f "docs/01-project/MDL_QUICK_REFERENCE.md" ]; then
            cat docs/01-project/MDL_QUICK_REFERENCE.md > /tmp/mdl-reference.txt
          else
            echo "No MDL quick reference found." > /tmp/mdl-reference.txt
          fi

          # Feature implementation pipeline
          if [ -f ".claude/skills/implement-mdl-feature.md" ]; then
            cat .claude/skills/implement-mdl-feature.md > /tmp/implement-skill.txt
          else
            echo "No implementation skill found." > /tmp/implement-skill.txt
          fi

          # MDL syntax design guidelines
          if [ -f ".claude/skills/design-mdl-syntax.md" ]; then
            cat .claude/skills/design-mdl-syntax.md > /tmp/design-skill.txt
          else
            echo "No design skill found." > /tmp/design-skill.txt
          fi

          # List existing skills (what features already exist)
          ls .claude/skills/mendix/ 2>/dev/null > /tmp/skills-list.txt || echo "none" > /tmp/skills-list.txt

          # List existing doctype tests (what's already covered)
          ls mdl-examples/doctype-tests/ 2>/dev/null > /tmp/doctype-tests.txt || echo "none" > /tmp/doctype-tests.txt

          # Current feature matrix
          if [ -f "docs/01-project/MDL_FEATURE_MATRIX.md" ]; then
            cat docs/01-project/MDL_FEATURE_MATRIX.md > /tmp/feature-matrix.txt
          else
            echo "No feature matrix found." > /tmp/feature-matrix.txt
          fi

      - name: Build API request
        run: |
          cat > /tmp/user-prompt.txt <<'PROMPT'
          Analyze this enhancement request and provide an implementation guide.

          ## Enhancement Request
          PROMPT
          cat /tmp/issue.json >> /tmp/user-prompt.txt

          cat >> /tmp/user-prompt.txt <<'PROMPT'

          ## Project Context (CLAUDE.md — architecture, key concepts, review checklist)
          PROMPT
          cat /tmp/claude-md.txt >> /tmp/user-prompt.txt

          cat >> /tmp/user-prompt.txt <<'PROMPT'

          ## MDL Syntax Design Guidelines
          PROMPT
          cat /tmp/design-skill.txt >> /tmp/user-prompt.txt

          cat >> /tmp/user-prompt.txt <<'PROMPT'

          ## Implementation Pipeline (step-by-step for new MDL features)
          PROMPT
          cat /tmp/implement-skill.txt >> /tmp/user-prompt.txt

          cat >> /tmp/user-prompt.txt <<'PROMPT'

          ## Current MDL Quick Reference (all existing syntax)
          PROMPT
          cat /tmp/mdl-reference.txt >> /tmp/user-prompt.txt

          cat >> /tmp/user-prompt.txt <<'PROMPT'

          ## Feature Matrix
          PROMPT
          cat /tmp/feature-matrix.txt >> /tmp/user-prompt.txt

          cat >> /tmp/user-prompt.txt <<'PROMPT'

          ## Existing skill files (features already documented)
          PROMPT
          cat /tmp/skills-list.txt >> /tmp/user-prompt.txt

          cat >> /tmp/user-prompt.txt <<'PROMPT'

          ## Existing doctype test scripts
          PROMPT
          cat /tmp/doctype-tests.txt >> /tmp/user-prompt.txt

          # Truncate to 120k to stay within API limits
          if [ "$(wc -c < /tmp/user-prompt.txt)" -gt 120000 ]; then
            head -c 120000 /tmp/user-prompt.txt > /tmp/user-prompt-truncated.txt
            mv /tmp/user-prompt-truncated.txt /tmp/user-prompt.txt
          fi

          jq -n --rawfile prompt /tmp/user-prompt.txt '{
            model: "nvidia/nemotron-3-super-120b-a12b:free",
            messages: [
              {
                role: "system",
                content: "You are an implementation guide for mxcli, a Go CLI tool that reads and modifies Mendix application projects (.mpr files) using MDL (Mendix Definition Language), a SQL-like syntax.\n\nYour job is to analyze enhancement requests and produce a practical implementation guide that helps developers (human or AI agent) implement the feature correctly.\n\nYou have deep knowledge of:\n- The full-stack MDL pipeline: ANTLR4 grammar → AST → visitor → executor → BSON writer\n- Mendix BSON serialization (storage names vs qualified names, required defaults)\n- MDL syntax design principles (reads as English, standard CRUD verbs, qualified names)\n- The PR review checklist (overlap, full-stack consistency, test coverage, security)\n\nYour response MUST include these sections:\n\n1. **Completeness Assessment** — Does the issue have enough detail? If NOT, list specific questions to ask the reporter (Mendix version? example of desired syntax? which Mendix concepts are involved?).\n\n2. **Overlap Check** — Could this already be done with existing syntax? List any existing features/skills that partially cover this.\n\n3. **Proposed MDL Syntax** — Draft the MDL syntax following design guidelines. Show 2-3 examples. If the issue already proposes syntax, evaluate it against guidelines.\n\n4. **Implementation Roadmap** — Step-by-step checklist of files to create/modify, following the full-stack pipeline. Be specific: name the actual files, functions, and patterns to follow.\n\n5. **BSON Investigation** — What BSON structures need to be understood? Suggest specific investigation steps (which reflection data to check, what to create in Studio Pro for reference).\n\n6. **Testing Strategy** — What doctype test script to add, what mx check validations to expect, what integration tests to write.\n\n7. **Gotchas & Risks** — Common pitfalls for this type of feature (storage name vs qualified name, missing BSON defaults, CE error codes to expect).\n\nKeep it practical and actionable. Reference specific files and patterns from the project context. If the enhancement is unclear, prioritize section 1 (questions) and keep other sections brief."
              },
              {
                role: "user",
                content: $prompt
              }
            ],
            max_tokens: 4000,
            temperature: 0.3
          }' > /tmp/request.json

          echo "Request payload size: $(wc -c < /tmp/request.json) bytes"

      - name: Call OpenRouter API
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
        run: |
          if [ -z "$OPENROUTER_API_KEY" ]; then
            echo "::warning::OPENROUTER_API_KEY secret is not set"
            exit 0
          fi

          HTTP_CODE=$(curl -s -w "%{http_code}" -o /tmp/response.json -X POST \
            -H "Authorization: Bearer $OPENROUTER_API_KEY" \
            -H "Content-Type: application/json" \
            -d @/tmp/request.json \
            https://openrouter.ai/api/v1/chat/completions)

          echo "HTTP status: $HTTP_CODE"

          if [ "$HTTP_CODE" != "200" ]; then
            echo "::warning::OpenRouter API returned HTTP $HTTP_CODE"
            cat /tmp/response.json | head -c 1000
            exit 0
          fi

          REVIEW=$(jq -r '.choices[0].message.content // empty' /tmp/response.json)

          if [ -z "$REVIEW" ]; then
            echo "::warning::AI returned empty content. Response:"
            cat /tmp/response.json | head -c 1000
            exit 0
          fi

          echo "$REVIEW" > /tmp/guide.txt
          echo "Guide generated ($(wc -c < /tmp/guide.txt) bytes)"

      - name: Post guide comment
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          if [ ! -f /tmp/guide.txt ]; then
            echo "No guide to post."
            exit 0
          fi

          {
            echo "## Enhancement Implementation Guide"
            echo ""
            cat /tmp/guide.txt
            echo ""
            echo "---"
            echo "*Automated guide via OpenRouter — [workflow source](${{ github.server_url }}/${{ github.repository }}/blob/main/.github/workflows/ai-enhancement-guide.yml)*"
          } > /tmp/comment.md

          gh issue comment ${{ github.event.issue.number }} \
            --repo ${{ github.repository }} \
            --body-file /tmp/comment.md