Merge pull request #43 from MarkusNeusinger/claude/rules-markdown-prompts-016ovKdqsbHgByE45Gxd3uZS

refactor: replace rules/ with prompts/ system

Author: MarkusNeusinger

.github/workflows/bot-validate-request.yml

@@ -85,139 +85,23 @@ jobs:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           claude_args: "--model opus"
           prompt: |
-            ## 🔍 Task: Validate Plot Request and Assign Spec ID
+            ## Task: Validate Plot Request and Assign Spec ID
 
-            A new plot request has been submitted. Your job is to:
-            1. Analyze the request
-            2. Check for duplicates/similar specs
-            3. Assign a meaningful spec ID (or flag as duplicate)
+            Read the rules from `prompts/spec-id-generator.md` and follow them.
 
             ### Issue Details
             - **Title:** ${{ github.event.issue.title }}
             - **Number:** #${{ github.event.issue.number }}
-
-            ### Issue Body:
+            - **Body:**
             ```
             ${{ github.event.issue.body }}
             ```
 
-            ### Instructions
-
-            #### Step 1: Read all existing specs
-            - List all files in `specs/` directory (excluding .template.md and VERSIONING.md)
-            - Read each spec file to understand what plots already exist
-            - Pay attention to: Description, Tags, Use Cases
-
-            #### Step 2: Analyze the request
-            - What type of plot is being requested? (scatter, bar, line, heatmap, etc.)
-            - What variant/feature is being requested? (basic, grouped, stacked, 3d, etc.)
-            - What makes it unique? (regression, animation, interactive, etc.)
-
-            #### Step 3: Check for duplicates
-            Compare the request against existing specs:
-            - **Exact duplicate**: Same plot type AND same features → Flag as duplicate
-            - **Very similar** (>80% overlap): Same type, minor differences → Suggest existing spec
-            - **Related but different**: Same type, different features → New spec OK
-            - **Completely new**: New plot type → New spec OK
-
-            #### Step 4: Generate spec ID (if not duplicate)
-
-            **ID Format:** `{plot-type}-{variant}-{modifier}` (all lowercase, hyphens only)
-
-            **Rules:**
-            - `plot-type`: The main visualization type (scatter, bar, line, heatmap, histogram, box, violin, pie, area, radar, etc.)
-            - `variant`: The main characteristic (basic, grouped, stacked, horizontal, 3d, multi, etc.)
-            - `modifier`: Optional - additional feature (regression, animated, interactive, annotated, etc.)
-
-            **Examples:**
-            - Basic scatter plot → `scatter-basic`
-            - Scatter with color mapping → `scatter-color-mapped`
-            - Scatter with linear regression → `scatter-regression-linear`
-            - 3D scatter with rotation → `scatter-3d-interactive`
-            - Grouped bar chart → `bar-grouped`
-            - Horizontal stacked bar → `bar-stacked-horizontal`
-            - Correlation heatmap → `heatmap-correlation`
-            - Annotated heatmap → `heatmap-annotated`
-            - Multi-line time series → `line-timeseries-multi`
-            - Box plot with outliers → `box-outliers-highlighted`
-
-            **ID must be:**
-            - Unique (not already used)
-            - Descriptive (someone can guess what it does)
-            - Concise (2-3 parts, max 40 characters)
-            - Lowercase with hyphens only
-
-            #### Step 5: Post comment with result
-
-            Use `gh issue comment` to post ONE of these responses:
-
-            **If DUPLICATE:**
-            ```markdown
-            ## 🔄 Duplicate Detected
-
-            This plot request appears to be a duplicate of an existing spec:
-
-            **Existing Spec:** `{existing-spec-id}`
-            **File:** `specs/{existing-spec-id}.md`
-
-            **Similarity:** {brief explanation of why it's a duplicate}
-
-            Please review the existing spec. If you believe this is different, please update the issue with more details about what makes it unique.
-
-            ---
-            🤖 *Generated by [validate-plot-request workflow](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*
-            ```
-
-            **If SIMILAR (suggest existing):**
-            ```markdown
-            ## ⚠️ Similar Spec Exists
-
-            This request is very similar to an existing spec:
-
-            **Existing Spec:** `{existing-spec-id}`
-            **File:** `specs/{existing-spec-id}.md`
-
-            **Differences:** {brief explanation}
-
-            **Options:**
-            1. Use the existing spec if it meets your needs
-            2. Update this issue to clarify the unique requirements
-            3. Consider this a variant of the existing spec
-
-            ---
-            🤖 *Generated by [validate-plot-request workflow](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*
-            ```
-
-            **If NEW (assign ID):**
-            ```markdown
-            ## ✅ Spec ID Assigned
-
-            **Assigned ID:** `{new-spec-id}`
-
-            **Rationale:** {1-2 sentences explaining why this ID was chosen}
-
-            **Next Steps:**
-            1. A maintainer will review this request
-            2. Once approved (label: `approved`), code generation will begin automatically
-            3. Implementations will be created for matplotlib and seaborn
-
-            **Spec will be created at:** `specs/{new-spec-id}.md`
-
-            ---
-            🤖 *Generated by [validate-plot-request workflow](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*
-            ```
-
-            #### Step 6: Update issue title with spec ID (if NEW)
-
-            After posting the comment, update the issue title to include the spec ID in brackets:
-            - Use: `gh issue edit ${{ github.event.issue.number }} --title "ORIGINAL_TITLE [{new-spec-id}]"`
-            - Example: "Plot: Basic bar chart" → "Plot: Basic bar chart [bar-basic]"
-            - This makes issues searchable by spec ID
+            ### Process
+            1. Read `prompts/spec-id-generator.md` for full instructions
+            2. List all existing specs in `specs/` directory
+            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 "..."`
 
-            ### Important Notes
-            - Do NOT create any files - only analyze and comment
-            - Do NOT add or remove labels
-            - Use `gh issue comment ${{ github.event.issue.number }} --body "..."` to post comment
-            - Use `gh issue edit ${{ github.event.issue.number }} --title "..."` to update title (only for NEW specs)
-            - Be helpful and constructive in feedback
-            - If the request is unclear, ask for clarification in the comment
+            Workflow URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}

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

@@ -121,89 +121,33 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          claude_args: "--model opus" # Use Haiku model for testing Opus for production
+          claude_args: "--model opus"
           additional_permissions: |
             actions: read
           prompt: |
-            ## 🎯 Task: Generate Plot Implementations for All 8 Libraries
-
-            This issue has been approved! Please generate implementations for **${{ steps.extract_spec.outputs.spec_id }}**.
-
-            ### Instructions
-
-            1. **Read the specification**
-               - File: `specs/${{ steps.extract_spec.outputs.spec_id }}.md`
-               - If file doesn't exist, create it from the issue body
-
-            2. **Read generation rules**
-               - `rules/generation/v1.0.0-draft/code-generation-rules.md`
-               - `rules/generation/v1.0.0-draft/quality-criteria.md`
-               - `rules/generation/v1.0.0-draft/self-review-checklist.md`
-
-            3. **Generate implementations for all 8 libraries** (in order of priority):
-
-               **3.1 matplotlib**
-               - Determine the correct plot type folder from spec (e.g., histogram, scatter, bar, line, etc.)
-               - Target: `plots/matplotlib/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
-               - Follow generation rules exactly
-               - Implement all spec requirements
-               - Use type hints, docstrings, validation
-               - Add standalone execution block (`if __name__ == '__main__':`)
-               - Self-review: Max 3 attempts to pass quality criteria
-
-               **3.2 seaborn**
-               - Determine the correct seaborn function folder (e.g., histplot, scatterplot, barplot, etc.)
-               - Target: `plots/seaborn/{seaborn_function}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
-               - Same requirements as matplotlib
-
-               **3.3 plotly**
-               - Target: `plots/plotly/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
-               - Use plotly.express or plotly.graph_objects as appropriate
-               - Ensure interactive features work
-
-               **3.4 bokeh**
-               - Target: `plots/bokeh/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
-               - Use bokeh.plotting interface
-               - Include output_file() for standalone HTML generation
-
-               **3.5 altair**
-               - Target: `plots/altair/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
-               - Use declarative Vega-Lite approach
-               - Leverage altair's data transformations where appropriate
-
-               **3.6 plotnine**
-               - Target: `plots/plotnine/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
-               - Use ggplot2-style grammar of graphics
-               - Follow plotnine idioms (aes, geom_*, etc.)
-
-               **3.7 pygal**
-               - Target: `plots/pygal/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
-               - Generate SVG output
-               - Use pygal's chart classes
-
-               **3.8 highcharts**
-               - Target: `plots/highcharts/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
-               - Use highcharts-core library (from highcharts_core import Chart)
-               - Generate interactive HTML output
-               - Note: Requires license for commercial use
-
-            4. **Create Pull Request**
-               - Branch: `auto/${{ steps.extract_spec.outputs.spec_id }}`
-               - Title: `feat: implement ${{ steps.extract_spec.outputs.spec_id }}`
-               - Include summary of generation results for ALL libraries
-               - Link to this issue (#${{ github.event.issue.number }})
-
-            ### Requirements
-            - Each implementation must pass self-review before moving to next
-            - Use deterministic sample data (fixed seeds or hardcoded data)
-            - Code must work standalone (no external files)
-            - Follow Python 3.10+ syntax
-            - Commit with clear messages
-            - If a library doesn't support the plot type well, note this in the PR but still try to create a reasonable approximation
-
-            ### Expected Outcome
-            - PR created with implementations for all 8 libraries
-            - All pass self-review (score ≥ 85)
-            - Tests will run automatically on PR
-
-            Please proceed with the generation!
+            ## Task: Generate Plot Implementations
+
+            Generate implementations for **${{ steps.extract_spec.outputs.spec_id }}** for all 8 libraries.
+
+            ### Read these files first:
+            1. `prompts/plot-generator.md` - Base generation rules
+            2. `prompts/quality-criteria.md` - Quality requirements
+            3. `specs/${{ steps.extract_spec.outputs.spec_id }}.md` - The specification (create from issue body if missing)
+
+            ### For each library, also read:
+            - `prompts/library/{library}.md` - Library-specific rules
+
+            ### Generate implementations for:
+            1. matplotlib → `plots/matplotlib/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
+            2. seaborn → `plots/seaborn/{function}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
+            3. plotly → `plots/plotly/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
+            4. bokeh → `plots/bokeh/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
+            5. altair → `plots/altair/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
+            6. plotnine → `plots/plotnine/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
+            7. pygal → `plots/pygal/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
+            8. highcharts → `plots/highcharts/{plot_type}/${{ steps.extract_spec.outputs.spec_id }}/default.py`
+
+            ### Create PR:
+            - Branch: `auto/${{ steps.extract_spec.outputs.spec_id }}`
+            - Title: `feat: implement ${{ steps.extract_spec.outputs.spec_id }}`
+            - Link to issue #${{ github.event.issue.number }}

CLAUDE.md

@@ -124,7 +124,7 @@ The same spec ID links implementations across all 8 supported libraries.
 - **`core/`**: Shared business logic (database, repositories, config)
 - **`api/`**: FastAPI backend (routers, schemas, dependencies)
 - **`app/`**: Next.js frontend (React + TypeScript + Vite + MUI)
-- **`rules/`**: Versioned rules for AI code generation and quality evaluation
+- **`prompts/`**: AI agent prompts for code generation, quality evaluation, and tagging
 - **`tests/unit/`**: Unit tests mirroring source structure
 - **`docs/`**: Architecture and workflow documentation
 
@@ -218,25 +218,49 @@ uv run alembic revision --autogenerate -m "description"
 uv run alembic upgrade head
 ```
 
-## Versioned Rules System
+## Prompts System
 
-The `rules/` directory contains versioned rules for AI code generation and quality evaluation.
+The `prompts/` directory contains AI agent prompts for code generation, quality evaluation, and tagging.
 
-### Working with Rules
+### Prompt Files
+
+| File | Purpose |
+|------|---------|
+| `plot-generator.md` | Base rules for all plot implementations |
+| `library/*.md` | Library-specific rules (8 files) |
+| `quality-criteria.md` | Definition of code/visual quality |
+| `quality-evaluator.md` | Multi-LLM evaluation prompt |
+| `auto-tagger.md` | Automatic tagging across 5 dimensions |
+| `spec-validator.md` | Validates plot request issues |
+| `spec-id-generator.md` | Assigns unique spec IDs |
+
+### Using Prompts
 
 ```bash
-# View current rules
-cat rules/versions.yaml
-cat rules/generation/v1.0.0-draft/code-generation-rules.md
+# View a prompt
+cat prompts/plot-generator.md
+cat prompts/library/matplotlib.md
 
-# Create new version
-cp -r rules/generation/v1.0.0-draft rules/generation/v1.1.0-draft
-# Edit files, then update rules/versions.yaml
+# Edit a prompt
+vim prompts/quality-criteria.md
+git commit -m "prompts: improve quality criteria"
 ```
 
-**Rule States**: draft → active → deprecated → archived
+**No folder versioning** - Git history tracks all changes. View old versions with `git log -p prompts/*.md`.
+
+### Workflow Integration
 
-**Why Versioned?** Enables A/B testing of rule improvements, provides audit trail, allows rollback.
+Workflows reference prompts instead of embedding long instructions:
+
+```yaml
+# Example usage in workflow
+prompt: |
+  $(cat prompts/plot-generator.md)
+  $(cat prompts/library/matplotlib.md)
+
+  ## Spec
+  $(cat specs/scatter-basic.md)
+```
 
 ## Implementation Guidelines
 
@@ -416,7 +440,7 @@ pytest --pdb       # Debug on failure
 - **docs/architecture/repository.md**: Directory structure
 - **docs/architecture/api.md**: API endpoints reference
 - **docs/architecture/database.md**: Database schema
-- **rules/README.md**: Rule versioning system
+- **prompts/README.md**: AI agent prompt system
 
 ## Project Philosophy