feat(workflows): unified plot-prepare workflow (#535)

## Summary

- Merge `bot-validate-request` + `gen-create-spec` into single
`plot-prepare.yml`
- Disable old workflows (renamed to `.yml.disabled`)
- Add update request analysis (validates if update reason is sensible)
- Update issue templates for clearer workflow

## New Workflow Flow

```
User creates Issue + plot-request label
    ↓
[plot-prepare.yml] (1 Claude Opus Call)
    ├── NEW: Duplicate check → Generate spec-id → Create branch → Create spec.md
    └── UPDATE: Validate spec exists → Analyze update reason → Create branch
    ↓
Comment with spec content + recommendation
    ↓
STOP ← waits for `approved` label
```

## Test Plan

- [ ] Create new plot request issue → verify spec is generated
- [ ] Create update request issue → verify analysis is posted
- [ ] Verify old workflows don't trigger (disabled)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: MarkusNeusinger

.github/ISSUE_TEMPLATE/plot-request.yml

@@ -1,6 +1,6 @@
 name: Plot Request
 description: Propose a new plot type for pyplots
-title: "Plot: "
+title: ""
 labels: ["plot-request"]
 body:
   - type: markdown
@@ -11,9 +11,9 @@ body:
         Describe the plot you'd like to see. Our AI will:
         1. Check for similar existing plots
         2. Assign a descriptive spec ID (e.g., `scatter-regression-linear`)
-        3. Generate implementations once approved
+        3. Create the specification for review
 
-        **No need to specify an ID** - just describe what you want!
+        **After submission:** A maintainer will review and add the `approved` label to start code generation.
 
   - type: textarea
     id: description

.github/ISSUE_TEMPLATE/plot-update.yml

@@ -1,28 +1,37 @@
 name: Plot Update
 description: Request updates or regeneration of an existing plot
-title: "[spec-id] [update] "
+title: "[SPEC-ID] [update] "
 labels: ["plot-request", "update"]
 body:
   - type: markdown
     attributes:
       value: |
         ## Plot Update Request
 
-        Use this form to update or regenerate an existing plot.
+        Use this to update or regenerate an existing plot.
 
-        **Title Format:**
-        - `[scatter-basic] [update] Regenerate` → Regenerate all 9 libraries
-        - `[scatter-basic] [update:seaborn] Fix colors` → Regenerate only seaborn
+        **Important:** Replace `SPEC-ID` in the title with the actual spec ID!
 
-        Replace `[spec-id]` in the title with the actual spec ID (e.g., `scatter-basic`).
+        **Title Examples:**
+        - `[scatter-basic] [update] Regenerate all` - All 9 libraries
+        - `[scatter-basic] [update:seaborn] Fix colors` - Only seaborn
 
-        After submitting, a maintainer will add the `approved` label to trigger regeneration.
+        **After submission:** A maintainer will review and add the `approved` label to start regeneration.
+
+  - type: input
+    id: spec_id
+    attributes:
+      label: Spec ID
+      description: "The spec ID to update (e.g., scatter-basic). Must match the title!"
+      placeholder: "scatter-basic"
+    validations:
+      required: true
 
   - type: dropdown
     id: target_library
     attributes:
-      label: Target Library (optional)
-      description: Update only a specific library, or leave empty for all. If you select a specific library, change [update] to [update:library] in the title.
+      label: Target Library
+      description: "Update specific library or all? If specific, change [update] to [update:library] in title."
       options:
         - All libraries
         - matplotlib
@@ -35,7 +44,7 @@ body:
         - highcharts
         - letsplot
     validations:
-      required: false
+      required: true
 
   - type: dropdown
     id: update_type
@@ -54,7 +63,7 @@ body:
     id: changes
     attributes:
       label: Requested Changes
-      description: Describe the changes to the spec or implementation (Claude will update the spec first if needed)
+      description: Describe the changes to the spec or implementation
       placeholder: |
         - Add grid lines for better readability
         - Change default color scheme to colorblind-friendly

.github/workflows/bot-ai-review.yml

@@ -202,12 +202,12 @@ jobs:
 
             ### Your Task
 
-            1. **Read the spec file**: `specs/${{ steps.pr.outputs.spec_id }}.md`
+            1. **Read the spec file**: `plots/${{ steps.pr.outputs.spec_id }}/spec.md`
                - Note all quality criteria listed
                - Understand the expected visual output
 
             2. **Read the ${{ steps.pr.outputs.library }} implementation**:
-               - `plots/${{ steps.pr.outputs.library }}/*/${{ steps.pr.outputs.spec_id }}/default.py`
+               - `plots/${{ steps.pr.outputs.spec_id }}/implementations/${{ steps.pr.outputs.library }}.py`
 
             3. **Read library-specific rules**:
                - `prompts/library/${{ steps.pr.outputs.library }}.md`

.github/workflows/bot-auto-merge.yml

@@ -282,7 +282,7 @@ jobs:
           - **Not Feasible:** $NOT_FEASIBLE
 
           ### Links
-          - **Spec:** \`specs/$SPEC_ID.md\`
+          - **Spec:** \`plots/$SPEC_ID/spec.md\`
           - **Parent Issue:** #$MAIN_ISSUE
 
           Closes #$MAIN_ISSUE
@@ -394,8 +394,8 @@ jobs:
           SPEC_ID="${{ steps.extract.outputs.spec_id }}"
           LIBRARY="${{ steps.extract.outputs.library }}"
 
-          # Find implementation file for this library
-          IMPL_FILE=$(find plots/$LIBRARY -name "default.py" -path "*/$SPEC_ID/*" 2>/dev/null | head -1 || echo "")
+          # Get implementation file path
+          IMPL_FILE="plots/${SPEC_ID}/implementations/${LIBRARY}.py"
           echo "impl_file=$IMPL_FILE" >> $GITHUB_OUTPUT
 
       - name: Update sub-issue to merged
@@ -621,8 +621,8 @@ jobs:
             exit 0
           fi
 
-          # Find implementation file
-          IMPL_FILE=$(find plots/$LIBRARY -name "default.py" -path "*/${SPEC_ID}/*" 2>/dev/null | head -1 || echo "")
+          # Get implementation file path
+          IMPL_FILE="plots/${SPEC_ID}/implementations/${LIBRARY}.py"
 
           # Update labels
           gh issue edit "$SUB_ISSUE" \
@@ -736,7 +736,7 @@ jobs:
           - **Not Feasible:** $NOT_FEASIBLE
 
           ### Links
-          - **Spec:** \`specs/$SPEC_ID.md\`
+          - **Spec:** \`plots/$SPEC_ID/spec.md\`
           - **Parent Issue:** #$MAIN_ISSUE
 
           Closes #$MAIN_ISSUE

.github/workflows/bot-auto-tag.yml

@@ -97,7 +97,7 @@ jobs:
           SPEC_ID="${{ steps.extract_spec.outputs.spec_id }}"
 
           # Read spec file
-          SPEC_FILE="specs/${SPEC_ID}.md"
+          SPEC_FILE="plots/${SPEC_ID}/spec.md"
           if [ -f "$SPEC_FILE" ]; then
             SPEC_CONTENT=$(cat "$SPEC_FILE")
             echo "spec_exists=true" >> $GITHUB_OUTPUT
@@ -106,8 +106,8 @@ jobs:
             SPEC_CONTENT=""
           fi
 
-          # Find plot files
-          PLOT_FILES=$(find plots -name "*.py" -path "*/${SPEC_ID}/*" 2>/dev/null | head -5)
+          # Find implementation files
+          PLOT_FILES=$(find "plots/${SPEC_ID}/implementations" -name "*.py" 2>/dev/null | head -5)
           echo "plot_files<<EOF" >> $GITHUB_OUTPUT
           echo "$PLOT_FILES" >> $GITHUB_OUTPUT
           echo "EOF" >> $GITHUB_OUTPUT
@@ -121,7 +121,7 @@ jobs:
           SPEC_ID="${{ steps.extract_spec.outputs.spec_id }}"
 
           # Read spec content
-          SPEC_CONTENT=$(cat "specs/${SPEC_ID}.md")
+          SPEC_CONTENT=$(cat "plots/${SPEC_ID}/spec.md")
 
           # Read first plot file as example
           PLOT_FILE=$(echo "${{ steps.read_files.outputs.plot_files }}" | head -1)

…ithub/workflows/bot-validate-request.yml …kflows/bot-validate-request.yml.disabled.github/workflows/bot-validate-request.yml renamed to .github/workflows/bot-validate-request.yml.disabled .github/workflows/bot-validate-request.yml renamed to .github/workflows/bot-validate-request.yml.disabled

@@ -112,7 +112,7 @@ jobs:
 
             ### Process
             1. Read `prompts/spec-id-generator.md` for full instructions
-            2. List all existing specs in `specs/` directory
+            2. List all existing specs in `plots/` directory (each subfolder has a spec.md)
             3. Analyze the request and check for duplicates
             4. Post comment using `gh issue comment ${{ github.event.issue.number }} --body "..."`
             5. If NEW: Update title with `gh issue edit ${{ github.event.issue.number }} --title "..."`

.github/workflows/ci-plottest.yml

@@ -6,7 +6,7 @@ on:
     types: [ opened, synchronize, reopened ]
     paths:
       - 'plots/**/*.py'
-      - 'specs/**/*.md'
+      - 'plots/**/spec.md'
 
 jobs:
   test-plots:

.github/workflows/gen-create-spec.yml …b/workflows/gen-create-spec.yml.disabled.github/workflows/gen-create-spec.yml renamed to .github/workflows/gen-create-spec.yml.disabled .github/workflows/gen-create-spec.yml renamed to .github/workflows/gen-create-spec.yml.disabled

@@ -143,14 +143,14 @@ jobs:
           SPEC_ID: ${{ steps.extract_spec.outputs.spec_id }}
           IS_UPDATE: ${{ steps.check.outputs.is_update }}
         run: |
-          if [ -f "specs/$SPEC_ID.md" ]; then
+          if [ -f "plots/$SPEC_ID/spec.md" ]; then
             echo "exists=true" >> $GITHUB_OUTPUT
-            echo "::notice::Spec file exists: specs/$SPEC_ID.md"
+            echo "::notice::Spec file exists: plots/$SPEC_ID/spec.md"
           else
             echo "exists=false" >> $GITHUB_OUTPUT
             # For updates, spec MUST exist
             if [[ "$IS_UPDATE" == "true" ]]; then
-              echo "::error::Update request but spec file does not exist: specs/$SPEC_ID.md"
+              echo "::error::Update request but spec file does not exist: plots/$SPEC_ID/spec.md"
               exit 1
             fi
             echo "::notice::Spec file does not exist yet (will be created)"
@@ -222,23 +222,27 @@ jobs:
 
             ### Instructions
 
-            1. Read the template: `specs/.template.md`
-            2. Read an example spec for reference: `specs/scatter-basic.md`
-            3. Read the spec validator rules: `prompts/spec-validator.md`
+            1. Read the template: `prompts/templates/spec.md`
+            2. Read the metadata template: `prompts/templates/metadata.yaml`
+            3. Read an example spec for reference: `plots/scatter-basic/spec.md`
+            4. Read the spec validator rules: `prompts/spec-validator.md`
 
-            4. Create the spec file at: `specs/${{ steps.extract_spec.outputs.spec_id }}.md`
+            5. Create the plot directory and files:
+               - Create directory: `plots/${{ steps.extract_spec.outputs.spec_id }}/`
+               - Create spec file: `plots/${{ steps.extract_spec.outputs.spec_id }}/spec.md`
+               - Create metadata file: `plots/${{ steps.extract_spec.outputs.spec_id }}/metadata.yaml`
+               - Create implementations folder: `plots/${{ steps.extract_spec.outputs.spec_id }}/implementations/`
                - Follow the template structure exactly
-               - Keep it simple and focused (description, data, tags, use cases)
-               - Include example data if helpful (inline or dataset reference)
+               - Keep it simple and focused (Description, Applications, Data, Notes)
                - Include realistic use cases with domain context
 
-            5. Do NOT commit or push - just create the file
+            6. Do NOT commit or push - just create the files
 
             ### Quality Requirements
-            - All required sections: Title, Description, Data, Tags, Use Cases
+            - Spec must have sections: Title, Description, Applications, Data, Notes
             - Description should clearly explain what the plot visualizes
-            - Data section should list required columns with types
-            - Use cases should be realistic and varied
+            - Data section should list required variables with types
+            - Applications should be realistic and varied
             - Keep it concise - AI uses central prompts for implementation details
 
       - name: Commit and push spec file
@@ -261,9 +265,9 @@ jobs:
             exit 0
           fi
 
-          # For new specs: check if spec file was created
-          if [ -f "specs/$SPEC_ID.md" ]; then
-            git add "specs/$SPEC_ID.md"
+          # For new specs: check if spec directory was created
+          if [ -d "plots/$SPEC_ID" ] && [ -f "plots/$SPEC_ID/spec.md" ]; then
+            git add "plots/$SPEC_ID/"
 
             # Check if there are changes to commit
             if git diff --cached --quiet; then
@@ -273,10 +277,10 @@ jobs:
 
             Created from issue #$ISSUE_NUMBER"
               git push -u origin "$BRANCH"
-              echo "::notice::Pushed spec file to $BRANCH"
+              echo "::notice::Pushed spec files to $BRANCH"
             fi
           else
-            echo "::error::Spec file was not created by Claude"
+            echo "::error::Spec directory was not created by Claude"
             exit 1
           fi
 
@@ -313,7 +317,7 @@ jobs:
 
           **Spec ID:** \`$SPEC_ID\`
           **Branch:** \`$BRANCH\`
-          **File:** \`specs/$SPEC_ID.md\`
+          **Directory:** \`plots/$SPEC_ID/\`
 
           ### Next Steps
           Triggering code generation for all 9 libraries...

.github/workflows/gen-library-impl.yml

@@ -158,29 +158,27 @@ jobs:
             2. `prompts/default-style-guide.md` - Visual style requirements (colors, fonts, dimensions)
             3. `prompts/quality-criteria.md` - Quality requirements
             4. `prompts/library/${{ inputs.library }}.md` - Library-specific rules
-            5. `specs/${{ inputs.spec_id }}.md` - The specification
+            5. `plots/${{ inputs.spec_id }}/spec.md` - The specification
 
             ### Step 2: Check for previous attempts
             ${{ steps.previous_attempts.outputs.has_history == 'true' && 'IMPORTANT: There are previous failed attempts. Read /tmp/previous_attempts.md to understand what went wrong and avoid repeating the same mistakes.' || 'This is the first attempt for this library.' }}
 
             ### Step 3: Generate implementation
             Create the implementation file at the correct path:
-            - `plots/${{ inputs.library }}/{plot_type}/${{ inputs.spec_id }}/default.py`
-
-            Determine {plot_type} from the spec (e.g., scatter, bar, line, heatmap).
+            - `plots/${{ inputs.spec_id }}/implementations/${{ inputs.library }}.py`
 
             ### Step 4: Test the implementation
             Run the implementation to verify it works:
             ```bash
             source .venv/bin/activate
-            MPLBACKEND=Agg python plots/${{ inputs.library }}/{plot_type}/${{ inputs.spec_id }}/default.py
+            MPLBACKEND=Agg python plots/${{ inputs.spec_id }}/implementations/${{ inputs.library }}.py
             ```
 
             ### Step 5: Format the code
             IMPORTANT: Run ruff to format and lint the code before committing:
             ```bash
-            uv run ruff format plots/${{ inputs.library }}/{plot_type}/${{ inputs.spec_id }}/default.py
-            uv run ruff check --fix plots/${{ inputs.library }}/{plot_type}/${{ inputs.spec_id }}/default.py
+            uv run ruff format plots/${{ inputs.spec_id }}/implementations/${{ inputs.library }}.py
+            uv run ruff check --fix plots/${{ inputs.spec_id }}/implementations/${{ inputs.library }}.py
             ```
 
             ### Step 6: Create PR (only if implementation is successful)
@@ -200,7 +198,7 @@ jobs:
               **Attempt:** ${{ inputs.attempt }}/3
 
               ## Implementation
-              - \`plots/${{ inputs.library }}/{plot_type}/${{ inputs.spec_id }}/default.py\`
+              - \`plots/${{ inputs.spec_id }}/implementations/${{ inputs.library }}.py\`
 
               Closes #${{ inputs.sub_issue_number }}"
               ```
@@ -236,8 +234,8 @@ jobs:
           ATTEMPT="${{ inputs.attempt }}"
           PR_NUMBER="${{ steps.pr.outputs.pr_number }}"
 
-          # Find the generated plot file
-          PLOT_FILE=$(find plots/$LIBRARY -name "default.py" -path "*/${SPEC_ID}/*" 2>/dev/null | head -1 || echo "")
+          # Get the implementation file path
+          PLOT_FILE="plots/${SPEC_ID}/implementations/${LIBRARY}.py"
 
           # Read the code if it exists
           if [ -f "$PLOT_FILE" ]; then

.github/workflows/gen-new-plot.yml

@@ -65,7 +65,7 @@ jobs:
 
       - name: Verify spec file exists
         run: |
-          SPEC_FILE="specs/${{ inputs.spec_id }}.md"
+          SPEC_FILE="plots/${{ inputs.spec_id }}/spec.md"
           if [ ! -f "$SPEC_FILE" ]; then
             echo "::error::Spec file not found: $SPEC_FILE"
             echo "::error::The feature branch should contain the spec file"
@@ -137,7 +137,7 @@ jobs:
             SUB_BODY="## [$SPEC_ID] $LIBRARY Implementation
 
           **Parent Issue:** #$PARENT_NUM
-          **Spec:** \`specs/$SPEC_ID.md\`
+          **Spec:** \`plots/$SPEC_ID/spec.md\`
           **Library:** $LIBRARY
           **Feature Branch:** \`$FEATURE_BRANCH\`