Compare commits
1 Commits
v5.7.0
...
249f8794ad
| Author | SHA1 | Date | |
|---|---|---|---|
| 249f8794ad |
@@ -6,7 +6,7 @@
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Project management plugins with Gitea and NetBox integrations",
|
||||
"version": "5.7.0"
|
||||
"version": "5.5.0"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
@@ -155,7 +155,7 @@
|
||||
},
|
||||
{
|
||||
"name": "data-platform",
|
||||
"version": "1.3.0",
|
||||
"version": "1.2.0",
|
||||
"description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
|
||||
"source": "./plugins/data-platform",
|
||||
"author": {
|
||||
|
||||
31
CHANGELOG.md
31
CHANGELOG.md
@@ -4,37 +4,6 @@ All notable changes to the Leo Claude Marketplace will be documented in this fil
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
||||
|
||||
## [5.7.0] - 2026-02-02
|
||||
|
||||
### Added
|
||||
- **data-platform**: New `data-advisor` agent for data integrity, schema, and dbt compliance validation
|
||||
- **data-platform**: New `data-integrity-audit.md` skill defining audit rules, severity levels, and scanning strategies
|
||||
- **data-platform**: New `/data-gate` command for binary pass/fail data integrity gates (projman integration)
|
||||
- **data-platform**: New `/data-review` command for comprehensive data integrity audits
|
||||
|
||||
### Changed
|
||||
- Domain Advisory Pattern now fully operational for both Viz and Data domains
|
||||
- projman orchestrator `Domain/Data` gates now resolve to live `/data-gate` command (previously fell through to "gate unavailable" warning)
|
||||
|
||||
---
|
||||
|
||||
## [5.6.0] - 2026-02-01
|
||||
|
||||
### Added
|
||||
- **Domain Advisory Pattern**: Cross-plugin integration enabling projman to consult domain-specific plugins during sprint lifecycle
|
||||
- **projman**: New `domain-consultation.md` skill for domain detection and gate protocols
|
||||
- **viz-platform**: New `design-reviewer` agent for design system compliance auditing
|
||||
- **viz-platform**: New `design-system-audit.md` skill defining audit rules and severity levels
|
||||
- **viz-platform**: New `/design-review` command for detailed design system audits
|
||||
- **viz-platform**: New `/design-gate` command for binary pass/fail validation gates
|
||||
- **Labels**: New `Domain/Viz` and `Domain/Data` labels for domain routing
|
||||
|
||||
### Changed
|
||||
- **projman planner**: Now loads domain-consultation skill and performs domain detection during planning
|
||||
- **projman orchestrator**: Now runs domain gates before marking Domain/* labeled issues as complete
|
||||
|
||||
---
|
||||
|
||||
## [5.5.0] - 2026-02-01
|
||||
|
||||
### Added
|
||||
|
||||
19
README.md
19
README.md
@@ -1,4 +1,4 @@
|
||||
# Leo Claude Marketplace - v5.6.0
|
||||
# Leo Claude Marketplace - v5.5.0
|
||||
|
||||
A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
|
||||
|
||||
@@ -138,22 +138,7 @@ Visualization toolkit with version-locked component validation and design token
|
||||
- 5 Page tools for multi-page app structure
|
||||
- Dual theme storage: user-level and project-level
|
||||
|
||||
**Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/design-review`, `/design-gate`, `/initial-setup`
|
||||
|
||||
## Domain Advisory Pattern
|
||||
|
||||
The marketplace supports cross-plugin domain advisory integration:
|
||||
|
||||
- **Domain Detection**: projman automatically detects when issues involve specialized domains (frontend/viz, data engineering)
|
||||
- **Acceptance Criteria**: Domain-specific acceptance criteria are added to issues during planning
|
||||
- **Execution Gates**: Domain validation gates (`/design-gate`, `/data-gate`) run before issue completion
|
||||
- **Extensible**: New domains can be added by creating advisory agents and gate commands
|
||||
|
||||
**Current Domains:**
|
||||
| Domain | Plugin | Gate Command |
|
||||
|--------|--------|--------------|
|
||||
| Visualization | viz-platform | `/design-gate` |
|
||||
| Data | data-platform | `/data-gate` |
|
||||
**Commands:** `/chart`, `/chart-export`, `/dashboard`, `/theme`, `/theme-new`, `/theme-css`, `/component`, `/accessibility-check`, `/breakpoints`, `/initial-setup`
|
||||
|
||||
## MCP Servers
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "data-platform",
|
||||
"version": "1.3.0",
|
||||
"version": "1.1.0",
|
||||
"description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
|
||||
"author": {
|
||||
"name": "Leo Miranda",
|
||||
|
||||
@@ -1,320 +0,0 @@
|
||||
---
|
||||
agent: data-advisor
|
||||
description: Reviews code for data integrity, schema validity, and dbt compliance using data-platform MCP tools
|
||||
triggers:
|
||||
- /data-review command
|
||||
- /data-gate command
|
||||
- projman orchestrator domain gate
|
||||
---
|
||||
|
||||
# Data Advisor Agent
|
||||
|
||||
You are a strict data integrity auditor. Your role is to review code for proper schema usage, dbt compliance, lineage integrity, and data quality standards.
|
||||
|
||||
## Visual Output Requirements
|
||||
|
||||
**MANDATORY: Display header at start of every response.**
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| DATA-PLATFORM - Data Advisor |
|
||||
| [Target Path] |
|
||||
+----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Trigger Conditions
|
||||
|
||||
Activate this agent when:
|
||||
- User runs `/data-review <path>`
|
||||
- User runs `/data-gate <path>`
|
||||
- Projman orchestrator requests data domain gate check
|
||||
- Code review includes database operations, dbt models, or data pipelines
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- skills/data-integrity-audit.md
|
||||
- skills/mcp-tools-reference.md
|
||||
|
||||
## Available MCP Tools
|
||||
|
||||
### PostgreSQL (Schema Validation)
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `pg_connect` | Verify database is reachable |
|
||||
| `pg_tables` | List tables, verify existence |
|
||||
| `pg_columns` | Get column details, verify types and constraints |
|
||||
| `pg_schemas` | List available schemas |
|
||||
| `pg_query` | Run diagnostic queries (SELECT only in review context) |
|
||||
|
||||
### PostGIS (Spatial Validation)
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `st_tables` | List tables with geometry columns |
|
||||
| `st_geometry_type` | Verify geometry types |
|
||||
| `st_srid` | Verify coordinate reference systems |
|
||||
| `st_extent` | Verify spatial extent is reasonable |
|
||||
|
||||
### dbt (Project Validation)
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `dbt_parse` | Validate project structure (ALWAYS run first) |
|
||||
| `dbt_compile` | Verify SQL renders correctly |
|
||||
| `dbt_test` | Run data tests |
|
||||
| `dbt_build` | Combined run + test |
|
||||
| `dbt_ls` | List all resources (models, tests, sources) |
|
||||
| `dbt_lineage` | Get model dependency graph |
|
||||
| `dbt_docs_generate` | Generate documentation for inspection |
|
||||
|
||||
### pandas (Data Validation)
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `describe` | Statistical summary for data quality checks |
|
||||
| `head` | Preview data for structural verification |
|
||||
| `list_data` | Check for stale DataFrames |
|
||||
|
||||
## Operating Modes
|
||||
|
||||
### Review Mode (default)
|
||||
|
||||
Triggered by `/data-review <path>`
|
||||
|
||||
**Characteristics:**
|
||||
- Produces detailed report with all findings
|
||||
- Groups findings by severity (FAIL/WARN/INFO)
|
||||
- Includes actionable recommendations with fixes
|
||||
- Does NOT block - informational only
|
||||
- Shows category compliance status
|
||||
|
||||
### Gate Mode
|
||||
|
||||
Triggered by `/data-gate <path>` or projman orchestrator domain gate
|
||||
|
||||
**Characteristics:**
|
||||
- Binary PASS/FAIL output
|
||||
- Only reports FAIL-level issues
|
||||
- Returns exit status for automation integration
|
||||
- Blocks completion on FAIL
|
||||
- Compact output for CI/CD pipelines
|
||||
|
||||
## Audit Workflow
|
||||
|
||||
### 1. Receive Target Path
|
||||
|
||||
Accept file or directory path from command invocation.
|
||||
|
||||
### 2. Determine Scope
|
||||
|
||||
Analyze target to identify what type of data work is present:
|
||||
|
||||
| Pattern | Type | Checks to Run |
|
||||
|---------|------|---------------|
|
||||
| `dbt_project.yml` present | dbt project | Full dbt validation |
|
||||
| `*.sql` files in dbt path | dbt models | Model compilation, lineage |
|
||||
| `*.py` with `pg_query`/`pg_execute` | Database operations | Schema validation |
|
||||
| `schema.yml` files | dbt schemas | Schema drift detection |
|
||||
| Migration files (`*_migration.sql`) | Schema changes | Full PostgreSQL + dbt checks |
|
||||
|
||||
### 3. Run Database Checks (if applicable)
|
||||
|
||||
```
|
||||
1. pg_connect → verify database reachable
|
||||
If fails: WARN, continue with file-based checks
|
||||
|
||||
2. pg_tables → verify expected tables exist
|
||||
If missing: FAIL
|
||||
|
||||
3. pg_columns on affected tables → verify types
|
||||
If mismatch: FAIL
|
||||
```
|
||||
|
||||
### 4. Run dbt Checks (if applicable)
|
||||
|
||||
```
|
||||
1. dbt_parse → validate project
|
||||
If fails: FAIL immediately (project broken)
|
||||
|
||||
2. dbt_ls → catalog all resources
|
||||
Record models, tests, sources
|
||||
|
||||
3. dbt_lineage on target models → check integrity
|
||||
Orphaned refs: FAIL
|
||||
|
||||
4. dbt_compile on target models → verify SQL
|
||||
Compilation errors: FAIL
|
||||
|
||||
5. dbt_test --select <targets> → run tests
|
||||
Test failures: FAIL
|
||||
|
||||
6. Cross-reference tests → models without tests
|
||||
Missing tests: WARN
|
||||
```
|
||||
|
||||
### 5. Run PostGIS Checks (if applicable)
|
||||
|
||||
```
|
||||
1. st_tables → list spatial tables
|
||||
If none found: skip PostGIS checks
|
||||
|
||||
2. st_srid → verify SRID correct
|
||||
Unexpected SRID: FAIL
|
||||
|
||||
3. st_geometry_type → verify expected types
|
||||
Wrong type: WARN
|
||||
|
||||
4. st_extent → sanity check bounding box
|
||||
Unreasonable extent: FAIL
|
||||
```
|
||||
|
||||
### 6. Scan Python Code (manual patterns)
|
||||
|
||||
For Python files with database operations:
|
||||
|
||||
| Pattern | Issue | Severity |
|
||||
|---------|-------|----------|
|
||||
| `f"SELECT * FROM {table}"` | SQL injection risk | WARN |
|
||||
| `f"INSERT INTO {table}"` | Unparameterized mutation | WARN |
|
||||
| `pg_execute` without WHERE in DELETE/UPDATE | Dangerous mutation | WARN |
|
||||
| Hardcoded connection strings | Credential exposure | WARN |
|
||||
|
||||
### 7. Generate Report
|
||||
|
||||
Output format depends on operating mode (see templates in `skills/data-integrity-audit.md`).
|
||||
|
||||
## Report Formats
|
||||
|
||||
### Gate Mode Output
|
||||
|
||||
**PASS:**
|
||||
```
|
||||
DATA GATE: PASS
|
||||
No blocking data integrity violations found.
|
||||
```
|
||||
|
||||
**FAIL:**
|
||||
```
|
||||
DATA GATE: FAIL
|
||||
|
||||
Blocking Issues (2):
|
||||
1. dbt/models/staging/stg_census.sql - Compilation error: column 'census_yr' not found
|
||||
Fix: Column was renamed to 'census_year' in source table. Update model.
|
||||
|
||||
2. portfolio_app/toronto/loaders/census.py:67 - References table 'census_raw' which does not exist
|
||||
Fix: Table was renamed to 'census_demographics' in migration 003.
|
||||
|
||||
Run /data-review for full audit report.
|
||||
```
|
||||
|
||||
### Review Mode Output
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| DATA-PLATFORM - Data Integrity Audit |
|
||||
| /path/to/project |
|
||||
+----------------------------------------------------------------------+
|
||||
|
||||
Target: /path/to/project
|
||||
Scope: 12 files scanned, 8 models checked, 3 tables verified
|
||||
|
||||
FINDINGS
|
||||
|
||||
FAIL (2)
|
||||
1. [dbt/models/staging/stg_census.sql] Compilation error
|
||||
Error: column 'census_yr' does not exist
|
||||
Fix: Column was renamed to 'census_year'. Update SELECT clause.
|
||||
|
||||
2. [portfolio_app/loaders/census.py:67] Missing table reference
|
||||
Error: Table 'census_raw' does not exist
|
||||
Fix: Table renamed to 'census_demographics' in migration 003.
|
||||
|
||||
WARN (3)
|
||||
1. [dbt/models/marts/dim_neighbourhoods.sql] Missing dbt test
|
||||
Issue: No unique test on neighbourhood_id
|
||||
Suggestion: Add unique test to schema.yml
|
||||
|
||||
2. [portfolio_app/toronto/queries.py:45] Hardcoded SQL
|
||||
Issue: f"SELECT * FROM {table_name}" without parameterization
|
||||
Suggestion: Use parameterized queries
|
||||
|
||||
3. [dbt/models/staging/stg_legacy.sql] Orphaned model
|
||||
Issue: No downstream consumers or exposures
|
||||
Suggestion: Remove if unused or add to exposure
|
||||
|
||||
INFO (1)
|
||||
1. [dbt/models/marts/fct_demographics.sql] Documentation gap
|
||||
Note: Model description missing in schema.yml
|
||||
Suggestion: Add description for discoverability
|
||||
|
||||
SUMMARY
|
||||
Schema: 2 issues
|
||||
Lineage: Intact
|
||||
dbt: 1 failure
|
||||
PostGIS: Not applicable
|
||||
|
||||
VERDICT: FAIL (2 blocking issues)
|
||||
```
|
||||
|
||||
## Severity Definitions
|
||||
|
||||
| Level | Criteria | Action Required |
|
||||
|-------|----------|-----------------|
|
||||
| **FAIL** | dbt parse/compile fails, missing tables/columns, type mismatches, broken lineage, invalid SRID | Must fix before completion |
|
||||
| **WARN** | Missing tests, hardcoded SQL, schema drift, orphaned models | Should fix |
|
||||
| **INFO** | Documentation gaps, optimization opportunities | Consider for improvement |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Response |
|
||||
|-------|----------|
|
||||
| Database not reachable | WARN: "PostgreSQL unavailable, skipping schema checks" - continue |
|
||||
| No dbt_project.yml | Skip dbt checks silently - not an error |
|
||||
| No PostGIS tables | Skip PostGIS checks silently - not an error |
|
||||
| MCP tool fails | WARN: "Tool {name} failed: {error}" - continue with remaining |
|
||||
| Empty path | PASS: "No data artifacts found in target path" |
|
||||
| Invalid path | Error: "Path not found: {path}" |
|
||||
|
||||
## Integration with projman
|
||||
|
||||
When called as a domain gate by projman orchestrator:
|
||||
|
||||
1. Receive path from orchestrator (changed files for the issue)
|
||||
2. Determine what type of data work changed
|
||||
3. Run audit in gate mode
|
||||
4. Return structured result:
|
||||
```
|
||||
Gate: data
|
||||
Status: PASS | FAIL
|
||||
Blocking: N issues
|
||||
Summary: Brief description
|
||||
```
|
||||
5. Orchestrator decides whether to proceed based on gate status
|
||||
|
||||
## Example Interactions
|
||||
|
||||
**User**: `/data-review dbt/models/staging/`
|
||||
**Agent**:
|
||||
1. Scans all .sql files in staging/
|
||||
2. Runs dbt_parse to validate project
|
||||
3. Runs dbt_compile on each model
|
||||
4. Checks lineage for orphaned refs
|
||||
5. Cross-references test coverage
|
||||
6. Returns detailed report
|
||||
|
||||
**User**: `/data-gate portfolio_app/toronto/`
|
||||
**Agent**:
|
||||
1. Scans for Python files with pg_query/pg_execute
|
||||
2. Checks if referenced tables exist
|
||||
3. Validates column types
|
||||
4. Returns PASS if clean, FAIL with blocking issues if not
|
||||
5. Compact output for automation
|
||||
|
||||
## Communication Style
|
||||
|
||||
Technical and precise. Report findings with exact locations, specific violations, and actionable fixes:
|
||||
|
||||
- "Table `census_demographics` column `population` is `varchar(50)` in PostgreSQL but referenced as `integer` in `stg_census.sql` line 14. This will cause a runtime cast error."
|
||||
- "Model `dim_neighbourhoods` has no `unique` test on `neighbourhood_id`. Add to `schema.yml` to prevent duplicates."
|
||||
- "Spatial extent for `toronto_boundaries` shows global coordinates (-180 to 180). Expected Toronto bbox (~-79.6 to -79.1 longitude). Likely missing ST_Transform or wrong SRID on import."
|
||||
@@ -1,104 +0,0 @@
|
||||
---
|
||||
description: Data integrity compliance gate (pass/fail) for sprint execution
|
||||
arguments:
|
||||
- name: path
|
||||
description: File or directory to validate
|
||||
required: true
|
||||
---
|
||||
|
||||
# /data-gate
|
||||
|
||||
Binary pass/fail validation for data integrity compliance. Used by projman orchestrator during sprint execution to gate issue completion.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/data-gate <path>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/data-gate ./dbt/models/staging/
|
||||
/data-gate ./portfolio_app/toronto/parsers/
|
||||
/data-gate ./dbt/
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
1. **Activates** the `data-advisor` agent in gate mode
|
||||
2. **Loads** the `skills/data-integrity-audit.md` skill
|
||||
3. **Determines scope** from target path:
|
||||
- dbt project directory: full dbt validation (parse, compile, test, lineage)
|
||||
- Python files with database operations: schema validation
|
||||
- SQL files: dbt model validation
|
||||
- Mixed: all applicable checks
|
||||
4. **Checks only FAIL-level violations:**
|
||||
- dbt parse failures (project broken)
|
||||
- dbt compilation errors (SQL invalid)
|
||||
- Missing tables/columns referenced in code
|
||||
- Data type mismatches that cause runtime errors
|
||||
- Broken lineage (orphaned model references)
|
||||
- PostGIS SRID mismatches
|
||||
5. **Returns binary result:**
|
||||
- `PASS` - No blocking violations found
|
||||
- `FAIL` - One or more blocking violations
|
||||
|
||||
## Output
|
||||
|
||||
### On PASS
|
||||
```
|
||||
DATA GATE: PASS
|
||||
No blocking data integrity violations found.
|
||||
```
|
||||
|
||||
### On FAIL
|
||||
```
|
||||
DATA GATE: FAIL
|
||||
|
||||
Blocking Issues (2):
|
||||
1. dbt/models/staging/stg_census.sql - Compilation error: column 'census_yr' not found
|
||||
Fix: Column was renamed to 'census_year' in source table. Update model.
|
||||
|
||||
2. portfolio_app/toronto/loaders/census.py:67 - References table 'census_raw' which does not exist
|
||||
Fix: Table was renamed to 'census_demographics' in migration 003.
|
||||
|
||||
Run /data-review for full audit report.
|
||||
```
|
||||
|
||||
## Integration with projman
|
||||
|
||||
This command is automatically invoked by the projman orchestrator when:
|
||||
|
||||
1. An issue has the `Domain/Data` label
|
||||
2. The orchestrator is about to mark the issue as complete
|
||||
3. The orchestrator passes the path of changed files
|
||||
|
||||
**Gate behavior:**
|
||||
- PASS: Issue can be marked complete
|
||||
- FAIL: Issue stays open, blocker comment added with failure details
|
||||
|
||||
## Differences from /data-review
|
||||
|
||||
| Aspect | /data-gate | /data-review |
|
||||
|--------|------------|--------------|
|
||||
| Output | Binary PASS/FAIL | Detailed report with all severities |
|
||||
| Severity | FAIL only | FAIL + WARN + INFO |
|
||||
| Purpose | Automation gate | Human review |
|
||||
| Verbosity | Minimal | Comprehensive |
|
||||
| Speed | Skips INFO checks | Full scan |
|
||||
|
||||
## When to Use
|
||||
|
||||
- **Sprint execution**: Automatic quality gates via projman
|
||||
- **CI/CD pipelines**: Automated data integrity checks
|
||||
- **Quick validation**: Fast pass/fail without full report
|
||||
- **Pre-merge checks**: Verify data changes before integration
|
||||
|
||||
For detailed findings including warnings and suggestions, use `/data-review` instead.
|
||||
|
||||
## Requirements
|
||||
|
||||
- data-platform MCP server must be running
|
||||
- For dbt checks: dbt project must be configured (auto-detected via `dbt_project.yml`)
|
||||
- For PostgreSQL checks: connection configured in `~/.config/claude/postgres.env`
|
||||
- If database or dbt unavailable: applicable checks skipped with warning (non-blocking degradation)
|
||||
@@ -1,149 +0,0 @@
|
||||
---
|
||||
description: Audit data integrity, schema validity, and dbt compliance
|
||||
arguments:
|
||||
- name: path
|
||||
description: File, directory, or dbt project to audit
|
||||
required: true
|
||||
---
|
||||
|
||||
# /data-review
|
||||
|
||||
Comprehensive data integrity audit producing a detailed report with findings at all severity levels. For human review and standalone codebase auditing.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/data-review <path>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/data-review ./dbt/
|
||||
/data-review ./portfolio_app/toronto/
|
||||
/data-review ./dbt/models/marts/
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
1. **Activates** the `data-advisor` agent in review mode
|
||||
2. **Scans target path** to determine scope:
|
||||
- Identifies dbt project files (.sql models, schema.yml, sources.yml)
|
||||
- Identifies Python files with database operations
|
||||
- Identifies migration files
|
||||
- Identifies PostGIS usage
|
||||
3. **Runs all check categories:**
|
||||
- Schema validity (PostgreSQL tables, columns, types)
|
||||
- dbt project health (parse, compile, test, lineage)
|
||||
- PostGIS compliance (SRID, geometry types, extent)
|
||||
- Data type consistency
|
||||
- Code patterns (unsafe SQL, hardcoded queries)
|
||||
4. **Produces detailed report** with all severity levels (FAIL, WARN, INFO)
|
||||
5. **Provides actionable recommendations** for each finding
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| DATA-PLATFORM - Data Integrity Audit |
|
||||
| /path/to/project |
|
||||
+----------------------------------------------------------------------+
|
||||
|
||||
Target: /path/to/project
|
||||
Scope: N files scanned, N models checked, N tables verified
|
||||
|
||||
FINDINGS
|
||||
|
||||
FAIL (N)
|
||||
1. [location] violation description
|
||||
Fix: actionable fix
|
||||
|
||||
WARN (N)
|
||||
1. [location] warning description
|
||||
Suggestion: improvement suggestion
|
||||
|
||||
INFO (N)
|
||||
1. [location] info description
|
||||
Note: context
|
||||
|
||||
SUMMARY
|
||||
Schema: Valid | N issues
|
||||
Lineage: Intact | N orphaned
|
||||
dbt: Passes | N failures
|
||||
PostGIS: Valid | N issues | Not applicable
|
||||
|
||||
VERDICT: PASS | FAIL (N blocking issues)
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
### Before Sprint Planning
|
||||
Audit data layer health to identify tech debt and inform sprint scope.
|
||||
```
|
||||
/data-review ./dbt/
|
||||
```
|
||||
|
||||
### During Code Review
|
||||
Get detailed data integrity findings alongside code review comments.
|
||||
```
|
||||
/data-review ./dbt/models/staging/stg_new_source.sql
|
||||
```
|
||||
|
||||
### After Migrations
|
||||
Verify schema changes didn't break anything downstream.
|
||||
```
|
||||
/data-review ./migrations/
|
||||
```
|
||||
|
||||
### Periodic Health Checks
|
||||
Regular data infrastructure audits for proactive maintenance.
|
||||
```
|
||||
/data-review ./data_pipeline/
|
||||
```
|
||||
|
||||
### New Project Onboarding
|
||||
Understand the current state of data architecture.
|
||||
```
|
||||
/data-review .
|
||||
```
|
||||
|
||||
## Severity Levels
|
||||
|
||||
| Level | Meaning | Gate Impact |
|
||||
|-------|---------|-------------|
|
||||
| **FAIL** | Blocking issues that will cause runtime errors | Would block `/data-gate` |
|
||||
| **WARN** | Quality issues that should be addressed | Does not block gate |
|
||||
| **INFO** | Suggestions for improvement | Does not block gate |
|
||||
|
||||
## Differences from /data-gate
|
||||
|
||||
`/data-review` gives you the full picture. `/data-gate` gives the orchestrator a yes/no.
|
||||
|
||||
| Aspect | /data-gate | /data-review |
|
||||
|--------|------------|--------------|
|
||||
| Output | Binary PASS/FAIL | Detailed report |
|
||||
| Severity | FAIL only | FAIL + WARN + INFO |
|
||||
| Purpose | Automation | Human review |
|
||||
| Verbosity | Minimal | Comprehensive |
|
||||
| Speed | Fast (skips INFO) | Thorough |
|
||||
|
||||
Use `/data-review` when you want to understand.
|
||||
Use `/data-gate` when you want to automate.
|
||||
|
||||
## Requirements
|
||||
|
||||
- data-platform MCP server must be running
|
||||
- For dbt checks: dbt project must be configured (auto-detected via `dbt_project.yml`)
|
||||
- For PostgreSQL checks: connection configured in `~/.config/claude/postgres.env`
|
||||
|
||||
**Graceful degradation:** If database or dbt unavailable, applicable checks are skipped with a note in the report rather than failing entirely.
|
||||
|
||||
## Skills Used
|
||||
|
||||
- `skills/data-integrity-audit.md` - Audit rules and patterns
|
||||
- `skills/mcp-tools-reference.md` - MCP tool reference
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/data-gate` - Binary pass/fail for automation
|
||||
- `/lineage` - Visualize dbt model dependencies
|
||||
- `/schema` - Explore database schema
|
||||
@@ -1,307 +0,0 @@
|
||||
---
|
||||
name: data-integrity-audit
|
||||
description: Rules and patterns for auditing data integrity, schema validity, and dbt compliance
|
||||
---
|
||||
|
||||
# Data Integrity Audit
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines what "data valid" means for the data-platform domain. This skill is loaded by the `data-advisor` agent for both review and gate modes during sprint execution and standalone audits.
|
||||
|
||||
---
|
||||
|
||||
## What to Check
|
||||
|
||||
| Check Category | What It Validates | MCP Tools Used |
|
||||
|----------------|-------------------|----------------|
|
||||
| **Schema Validity** | Tables exist, columns have correct types, constraints present, no orphaned columns | `pg_tables`, `pg_columns`, `pg_schemas` |
|
||||
| **dbt Project Health** | Project parses without errors, models compile, tests defined for critical models | `dbt_parse`, `dbt_compile`, `dbt_test`, `dbt_ls` |
|
||||
| **Lineage Integrity** | No orphaned models (referenced but missing), no circular dependencies, upstream sources exist | `dbt_lineage`, `dbt_ls` |
|
||||
| **Data Type Consistency** | DataFrame dtypes match expected schema, no silent type coercion, date formats consistent | `describe`, `head`, `pg_columns` |
|
||||
| **PostGIS Compliance** | Spatial tables have correct SRID, geometry types match expectations, extent is reasonable | `st_tables`, `st_geometry_type`, `st_srid`, `st_extent` |
|
||||
| **Query Safety** | SELECT queries used for reads (not raw SQL for mutations), parameterized patterns | Code review - manual pattern check |
|
||||
|
||||
---
|
||||
|
||||
## Common Violations
|
||||
|
||||
### FAIL-Level Violations (Block Gate)
|
||||
|
||||
| Violation | Detection Method | Example |
|
||||
|-----------|-----------------|---------|
|
||||
| dbt parse failure | `dbt_parse` returns error | Project YAML invalid, missing ref targets |
|
||||
| dbt compilation error | `dbt_compile` fails | SQL syntax error, undefined column reference |
|
||||
| Missing table/column | `pg_tables`, `pg_columns` lookup | Code references `census_raw` but table doesn't exist |
|
||||
| Type mismatch | Compare `pg_columns` vs dbt schema | Column is `varchar` in DB but model expects `integer` |
|
||||
| Broken lineage | `dbt_lineage` shows orphaned refs | Model references `stg_old_format` which doesn't exist |
|
||||
| PostGIS SRID mismatch | `st_srid` returns unexpected value | Geometry column has SRID 0 instead of 4326 |
|
||||
| Unreasonable spatial extent | `st_extent` returns global bbox | Toronto data shows coordinates in China |
|
||||
|
||||
### WARN-Level Violations (Report, Don't Block)
|
||||
|
||||
| Violation | Detection Method | Example |
|
||||
|-----------|-----------------|---------|
|
||||
| Missing dbt tests | `dbt_ls` shows model without test | `dim_customers` has no `unique` test on `customer_id` |
|
||||
| Undocumented columns | dbt schema.yml missing descriptions | Model columns have no documentation |
|
||||
| Schema drift | `pg_columns` vs dbt schema.yml | Column exists in DB but not in dbt YAML |
|
||||
| Hardcoded SQL | Scan Python for string concatenation | `f"SELECT * FROM {table}"` without parameterization |
|
||||
| Orphaned model | `dbt_lineage` shows no downstream | `stg_legacy` has no consumers and no exposure |
|
||||
|
||||
### INFO-Level Violations (Suggestions Only)
|
||||
|
||||
| Violation | Detection Method | Example |
|
||||
|-----------|-----------------|---------|
|
||||
| Missing indexes | Query pattern suggests need | Frequent filter on non-indexed column |
|
||||
| Documentation gaps | dbt docs incomplete | Missing model description |
|
||||
| Unused models | `dbt_ls` vs actual queries | Model exists but never selected |
|
||||
| Optimization opportunity | `describe` shows data patterns | Column has low cardinality, could be enum |
|
||||
|
||||
---
|
||||
|
||||
## Severity Classification
|
||||
|
||||
| Severity | When to Apply | Gate Behavior |
|
||||
|----------|--------------|---------------|
|
||||
| **FAIL** | Broken lineage, models that won't compile, missing tables/columns, data type mismatches that cause runtime errors, invalid SRID | Blocks issue completion |
|
||||
| **WARN** | Missing dbt tests, undocumented columns, schema drift, hardcoded SQL, orphaned models | Does NOT block gate, included in review report |
|
||||
| **INFO** | Optimization opportunities, documentation gaps, unused models | Review report only |
|
||||
|
||||
### Severity Decision Tree
|
||||
|
||||
```
|
||||
Is the dbt project broken (parse/compile fails)?
|
||||
YES -> FAIL
|
||||
NO -> Does code reference non-existent tables/columns?
|
||||
YES -> FAIL
|
||||
NO -> Would this cause a runtime error?
|
||||
YES -> FAIL
|
||||
NO -> Does it violate data quality standards?
|
||||
YES -> WARN
|
||||
NO -> Is it an optimization/documentation suggestion?
|
||||
YES -> INFO
|
||||
NO -> Not a violation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scanning Strategy
|
||||
|
||||
### For dbt Projects
|
||||
|
||||
1. **Parse validation** (ALWAYS FIRST)
|
||||
```
|
||||
dbt_parse → if fails, immediate FAIL (project is broken)
|
||||
```
|
||||
|
||||
2. **Catalog resources**
|
||||
```
|
||||
dbt_ls → list all models, tests, sources, exposures
|
||||
```
|
||||
|
||||
3. **Lineage check**
|
||||
```
|
||||
dbt_lineage on changed models → check upstream/downstream integrity
|
||||
```
|
||||
|
||||
4. **Compilation check**
|
||||
```
|
||||
dbt_compile on changed models → verify SQL renders correctly
|
||||
```
|
||||
|
||||
5. **Test execution**
|
||||
```
|
||||
dbt_test --select <changed_models> → verify tests pass
|
||||
```
|
||||
|
||||
6. **Test coverage audit**
|
||||
```
|
||||
Cross-reference dbt_ls tests against model list → flag models without tests (WARN)
|
||||
```
|
||||
|
||||
### For PostgreSQL Schema Changes
|
||||
|
||||
1. **Table verification**
|
||||
```
|
||||
pg_tables → verify expected tables exist
|
||||
```
|
||||
|
||||
2. **Column validation**
|
||||
```
|
||||
pg_columns on affected tables → verify types match expectations
|
||||
```
|
||||
|
||||
3. **Schema comparison**
|
||||
```
|
||||
Compare pg_columns output against dbt schema.yml → flag drift
|
||||
```
|
||||
|
||||
### For PostGIS/Spatial Data
|
||||
|
||||
1. **Spatial table scan**
|
||||
```
|
||||
st_tables → list tables with geometry columns
|
||||
```
|
||||
|
||||
2. **SRID validation**
|
||||
```
|
||||
st_srid → verify SRID is correct for expected region
|
||||
Expected: 4326 (WGS84) for GPS data, local projections for regional data
|
||||
```
|
||||
|
||||
3. **Geometry type check**
|
||||
```
|
||||
st_geometry_type → verify expected types (Point, Polygon, etc.)
|
||||
```
|
||||
|
||||
4. **Extent sanity check**
|
||||
```
|
||||
st_extent → verify bounding box is reasonable for expected region
|
||||
Toronto data should be ~(-79.6 to -79.1, 43.6 to 43.9)
|
||||
```
|
||||
|
||||
### For DataFrame/pandas Operations
|
||||
|
||||
1. **Data quality check**
|
||||
```
|
||||
describe → check for unexpected nulls, type issues, outliers
|
||||
```
|
||||
|
||||
2. **Structure verification**
|
||||
```
|
||||
head → verify data structure matches expectations
|
||||
```
|
||||
|
||||
3. **Memory management**
|
||||
```
|
||||
list_data → verify no stale DataFrames from previous failed runs
|
||||
```
|
||||
|
||||
### For Python Code (Manual Scan)
|
||||
|
||||
1. **SQL injection patterns**
|
||||
- Scan for f-strings with table/column names
|
||||
- Check for string concatenation in queries
|
||||
- Look for `.format()` calls with SQL
|
||||
|
||||
2. **Mutation safety**
|
||||
- `pg_execute` usage should be intentional, not accidental
|
||||
- Verify DELETE/UPDATE have WHERE clauses
|
||||
|
||||
3. **Credential exposure**
|
||||
- No hardcoded connection strings
|
||||
- No credentials in code (check for `.env` usage)
|
||||
|
||||
---
|
||||
|
||||
## Report Templates
|
||||
|
||||
### Gate Mode (Compact)
|
||||
|
||||
```
|
||||
DATA GATE: PASS
|
||||
No blocking data integrity violations found.
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
DATA GATE: FAIL
|
||||
|
||||
Blocking Issues (N):
|
||||
1. <location> - <violation description>
|
||||
Fix: <actionable fix>
|
||||
|
||||
2. <location> - <violation description>
|
||||
Fix: <actionable fix>
|
||||
|
||||
Run /data-review for full audit report.
|
||||
```
|
||||
|
||||
### Review Mode (Detailed)
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| DATA-PLATFORM - Data Integrity Audit |
|
||||
| [Target Path] |
|
||||
+----------------------------------------------------------------------+
|
||||
|
||||
Target: <scanned path or project>
|
||||
Scope: N files scanned, N models checked, N tables verified
|
||||
|
||||
FINDINGS
|
||||
|
||||
FAIL (N)
|
||||
1. [location] violation description
|
||||
Fix: actionable fix
|
||||
|
||||
2. [location] violation description
|
||||
Fix: actionable fix
|
||||
|
||||
WARN (N)
|
||||
1. [location] warning description
|
||||
Suggestion: improvement suggestion
|
||||
|
||||
2. [location] warning description
|
||||
Suggestion: improvement suggestion
|
||||
|
||||
INFO (N)
|
||||
1. [location] info description
|
||||
Note: context
|
||||
|
||||
SUMMARY
|
||||
Schema: Valid | N issues
|
||||
Lineage: Intact | N orphaned
|
||||
dbt: Passes | N failures
|
||||
PostGIS: Valid | N issues | Not applicable
|
||||
|
||||
VERDICT: PASS | FAIL (N blocking issues)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skip Patterns
|
||||
|
||||
Do not flag violations in:
|
||||
|
||||
- `**/tests/**` - Test files may have intentional violations
|
||||
- `**/__pycache__/**` - Compiled files
|
||||
- `**/fixtures/**` - Test fixtures
|
||||
- `**/.scratch/**` - Temporary working files
|
||||
- Files with `# noqa: data-audit` comment
|
||||
- Migration files marked as historical
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Behavior |
|
||||
|----------|----------|
|
||||
| Database not reachable (`pg_connect` fails) | WARN, skip PostgreSQL checks, continue with file-based |
|
||||
| dbt not configured (no `dbt_project.yml`) | Skip dbt checks entirely, not an error |
|
||||
| No PostGIS tables found | Skip PostGIS checks, not an error |
|
||||
| MCP tool call fails | Report as WARN with tool name, continue with remaining checks |
|
||||
| No data files in scanned path | Report "No data artifacts found" - PASS (nothing to fail) |
|
||||
| Empty directory | Report "No files found in path" - PASS |
|
||||
|
||||
---
|
||||
|
||||
## Integration Notes
|
||||
|
||||
### projman Orchestrator
|
||||
|
||||
When called as a domain gate:
|
||||
1. Orchestrator detects `Domain/Data` label on issue
|
||||
2. Orchestrator identifies changed files
|
||||
3. Orchestrator invokes `/data-gate <path>`
|
||||
4. Agent runs gate mode scan
|
||||
5. Returns PASS/FAIL to orchestrator
|
||||
6. Orchestrator decides whether to complete issue
|
||||
|
||||
### Standalone Usage
|
||||
|
||||
For manual audits:
|
||||
1. User runs `/data-review <path>`
|
||||
2. Agent runs full review mode scan
|
||||
3. Returns detailed report with all severity levels
|
||||
4. User decides on actions
|
||||
@@ -75,6 +75,7 @@ Execute `skills/dependency-management.md` - Check for file conflicts before para
|
||||
Execute `skills/progress-tracking.md` - Manage status labels, parse progress comments.
|
||||
|
||||
### 6.5. Domain Gate Checks
|
||||
|
||||
Execute `skills/domain-consultation.md` (Execution Gate Protocol section):
|
||||
|
||||
1. **Before marking any issue as complete**, check for `Domain/*` labels
|
||||
|
||||
@@ -20,7 +20,6 @@ You are the **Planner Agent** - a methodical architect who thoroughly analyzes r
|
||||
- skills/sprint-approval.md
|
||||
- skills/planning-workflow.md
|
||||
- skills/label-taxonomy/labels-reference.md
|
||||
- skills/domain-consultation.md
|
||||
|
||||
## Your Personality
|
||||
|
||||
@@ -67,25 +66,10 @@ Execute `skills/wiki-conventions.md` - Create proposal and implementation pages.
|
||||
### 6. Task Sizing
|
||||
Execute `skills/task-sizing.md` - **REFUSE to create L/XL tasks without breakdown.**
|
||||
|
||||
### 7. Domain Consultation
|
||||
|
||||
Execute `skills/domain-consultation.md` (Planning Protocol section):
|
||||
|
||||
1. **After drafting issues but BEFORE creating them in Gitea**
|
||||
2. **Analyze each issue for domain signals:**
|
||||
- Check planned labels for `Component/Frontend`, `Component/UI` -> Domain/Viz
|
||||
- Check planned labels for `Component/Database`, `Component/Data` -> Domain/Data
|
||||
- Scan issue description for domain keywords (see skill for full list)
|
||||
3. **For detected domains, append acceptance criteria:**
|
||||
- Domain/Viz: Design System Compliance checklist
|
||||
- Domain/Data: Data Integrity checklist
|
||||
4. **Add corresponding `Domain/*` label** to the issue's label set
|
||||
5. **Document in planning summary** which issues have domain gates active
|
||||
|
||||
### 8. Issue Creation
|
||||
### 7. Issue Creation
|
||||
Execute `skills/issue-conventions.md` - Use proper format with wiki references.
|
||||
|
||||
### 9. Request Approval
|
||||
### 8. Request Approval
|
||||
Execute `skills/sprint-approval.md` - Planning DOES NOT equal execution permission.
|
||||
|
||||
## Critical Reminders
|
||||
@@ -97,7 +81,6 @@ Execute `skills/sprint-approval.md` - Planning DOES NOT equal execution permissi
|
||||
5. **ALWAYS search lessons** - Past experience informs better planning
|
||||
6. **ALWAYS include wiki reference** - Every issue links to implementation wiki page
|
||||
7. **ALWAYS use proper title format** - `[Sprint XX] <type>: <description>`
|
||||
8. **ALWAYS check domain signals** - Every issue gets checked for viz/data domain applicability before creation
|
||||
|
||||
## Your Mission
|
||||
|
||||
|
||||
@@ -1,163 +0,0 @@
|
||||
---
|
||||
name: domain-consultation
|
||||
description: Cross-plugin domain consultation for specialized planning and validation
|
||||
---
|
||||
|
||||
# Domain Consultation
|
||||
|
||||
## Purpose
|
||||
|
||||
Enables projman agents to detect domain-specific work and consult specialized plugins for expert validation during planning and execution phases. This skill is the backbone of the Domain Advisory Pattern.
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
| Agent | Phase | Action |
|
||||
|-------|-------|--------|
|
||||
| Planner | After task sizing, before issue creation | Detect domains, add acceptance criteria |
|
||||
| Orchestrator | Before marking issue complete | Run domain gates, block if violations |
|
||||
| Code Reviewer | During review | Include domain compliance in findings |
|
||||
|
||||
---
|
||||
|
||||
## Domain Detection Rules
|
||||
|
||||
| Signal Type | Detection Pattern | Domain Plugin | Action |
|
||||
|-------------|-------------------|---------------|--------|
|
||||
| Label-based | `Component/Frontend`, `Component/UI` | viz-platform | Add design system criteria, apply `Domain/Viz` |
|
||||
| Content-based | Keywords: DMC, Dash, layout, theme, component, dashboard, chart, responsive, color, UI, frontend, Plotly | viz-platform | Same as above |
|
||||
| Label-based | `Component/Database`, `Component/Data` | data-platform | Add data validation criteria, apply `Domain/Data` |
|
||||
| Content-based | Keywords: schema, migration, pipeline, dbt, table, column, query, PostgreSQL, lineage, data model | data-platform | Same as above |
|
||||
| Both signals | Frontend + Data signals present | Both plugins | Apply both sets of criteria |
|
||||
|
||||
---
|
||||
|
||||
## Planning Protocol
|
||||
|
||||
When creating issues, the planner MUST:
|
||||
|
||||
1. **Analyze each issue** for domain signals (check labels AND scan description for keywords)
|
||||
|
||||
2. **For Domain/Viz issues**, append this acceptance criteria block:
|
||||
```markdown
|
||||
## Design System Compliance
|
||||
- [ ] All DMC components validated against registry
|
||||
- [ ] Theme tokens used (no hardcoded colors/sizes)
|
||||
- [ ] Accessibility check passed (WCAG contrast)
|
||||
- [ ] Responsive breakpoints verified
|
||||
```
|
||||
|
||||
3. **For Domain/Data issues**, append this acceptance criteria block:
|
||||
```markdown
|
||||
## Data Integrity
|
||||
- [ ] Schema changes validated
|
||||
- [ ] dbt tests pass
|
||||
- [ ] Lineage intact (no orphaned models)
|
||||
- [ ] Data types verified
|
||||
```
|
||||
|
||||
4. **Apply the corresponding `Domain/*` label** to route the issue through gates
|
||||
|
||||
5. **Document in planning summary** which issues have domain gates active
|
||||
|
||||
---
|
||||
|
||||
## Execution Gate Protocol
|
||||
|
||||
Before marking any issue as complete, the orchestrator MUST:
|
||||
|
||||
1. **Check issue labels** for `Domain/*` labels
|
||||
|
||||
2. **If `Domain/Viz` label present:**
|
||||
- Identify files changed by this issue
|
||||
- Invoke `/design-gate <path-to-changed-files>`
|
||||
- Gate PASS → proceed to mark issue complete
|
||||
- Gate FAIL → add comment to issue with failure details, keep issue open
|
||||
|
||||
3. **If `Domain/Data` label present:**
|
||||
- Identify files changed by this issue
|
||||
- Invoke `/data-gate <path-to-changed-files>`
|
||||
- Gate PASS → proceed to mark issue complete
|
||||
- Gate FAIL → add comment to issue with failure details, keep issue open
|
||||
|
||||
4. **If gate command unavailable** (MCP server not running):
|
||||
- Warn user: "Domain gate unavailable - proceeding without validation"
|
||||
- Proceed with completion (non-blocking degradation)
|
||||
- Do NOT silently skip - always inform user
|
||||
|
||||
---
|
||||
|
||||
## Review Protocol
|
||||
|
||||
During code review, the code reviewer SHOULD:
|
||||
|
||||
1. After completing standard code quality and security checks, check for `Domain/*` labels
|
||||
|
||||
2. **If Domain/Viz:** Include "Design System Compliance" section in review report
|
||||
- Reference `/design-review` findings if available
|
||||
- Check for hardcoded colors, invalid props, accessibility issues
|
||||
|
||||
3. **If Domain/Data:** Include "Data Integrity" section in review report
|
||||
- Reference `/data-gate` findings if available
|
||||
- Check for schema validity, lineage integrity
|
||||
|
||||
---
|
||||
|
||||
## Extensibility
|
||||
|
||||
To add a new domain (e.g., `Domain/Infra` for cmdb-assistant):
|
||||
|
||||
1. **In domain plugin:** Create advisory agent + gate command
|
||||
- Agent: `agents/infra-advisor.md`
|
||||
- Gate command: `commands/infra-gate.md`
|
||||
- Audit skill: `skills/infra-audit.md`
|
||||
|
||||
2. **In this skill:** Add detection rules to the Detection Rules table above
|
||||
- Define label-based signals (e.g., `Component/Infrastructure`)
|
||||
- Define content-based keywords (e.g., "server", "network", "NetBox")
|
||||
|
||||
3. **In label taxonomy:** Add `Domain/Infra` label with appropriate color
|
||||
- Update `plugins/projman/skills/label-taxonomy/labels-reference.md`
|
||||
|
||||
4. **No changes needed** to planner.md or orchestrator.md agent files
|
||||
- They read this skill dynamically
|
||||
- Detection rules table is the single source of truth
|
||||
|
||||
This pattern ensures domain expertise stays in domain plugins while projman orchestrates when to ask.
|
||||
|
||||
---
|
||||
|
||||
## Domain Acceptance Criteria Templates
|
||||
|
||||
### Design System Compliance (Domain/Viz)
|
||||
|
||||
```markdown
|
||||
## Design System Compliance
|
||||
- [ ] All DMC components validated against registry
|
||||
- [ ] Theme tokens used (no hardcoded colors/sizes)
|
||||
- [ ] Accessibility check passed (WCAG contrast)
|
||||
- [ ] Responsive breakpoints verified
|
||||
```
|
||||
|
||||
### Data Integrity (Domain/Data)
|
||||
|
||||
```markdown
|
||||
## Data Integrity
|
||||
- [ ] Schema changes validated
|
||||
- [ ] dbt tests pass
|
||||
- [ ] Lineage intact (no orphaned models)
|
||||
- [ ] Data types verified
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Gate Command Reference
|
||||
|
||||
| Domain | Gate Command | Review Command | Advisory Agent |
|
||||
|--------|--------------|----------------|----------------|
|
||||
| Viz | `/design-gate <path>` | `/design-review <path>` | `design-reviewer` |
|
||||
| Data | `/data-gate <path>` | `/data-review <path>` | `data-advisor` |
|
||||
|
||||
Gate commands return binary PASS/FAIL for automation.
|
||||
Review commands return detailed reports for human review.
|
||||
@@ -13,7 +13,7 @@ description: Dynamic reference for Gitea label taxonomy (organization + reposito
|
||||
|
||||
This skill provides the current label taxonomy used for issue classification in Gitea. Labels are **fetched dynamically** from Gitea and should never be hardcoded.
|
||||
|
||||
**Current Taxonomy:** 49 labels (31 organization + 18 repository)
|
||||
**Current Taxonomy:** 47 labels (31 organization + 16 repository)
|
||||
|
||||
## Organization Labels (31)
|
||||
|
||||
@@ -66,7 +66,7 @@ Organization-level labels are shared across all repositories in your configured
|
||||
- `Status/Failed` (#de350b) - Implementation attempted but failed, needs investigation
|
||||
- `Status/Deferred` (#6554c0) - Moved to a future sprint or backlog
|
||||
|
||||
## Repository Labels (18)
|
||||
## Repository Labels (16)
|
||||
|
||||
Repository-level labels are specific to each project.
|
||||
|
||||
@@ -90,27 +90,6 @@ Repository-level labels are specific to each project.
|
||||
- `Tech/Vue` (#42b883) - Vue.js frontend framework
|
||||
- `Tech/FastAPI` (#009688) - FastAPI backend framework
|
||||
|
||||
### Domain (2 labels)
|
||||
|
||||
Cross-plugin integration labels for domain-specific validation gates.
|
||||
|
||||
| Label | Color | Description |
|
||||
|-------|-------|-------------|
|
||||
| `Domain/Viz` | `#7c4dff` | Issue involves visualization/frontend — triggers viz-platform design gates |
|
||||
| `Domain/Data` | `#00bfa5` | Issue involves data engineering — triggers data-platform data gates |
|
||||
|
||||
**Detection Rules:**
|
||||
|
||||
**Domain/Viz:**
|
||||
- Keywords: "dashboard", "chart", "theme", "DMC", "component", "layout", "responsive", "color", "UI", "frontend", "Dash", "Plotly"
|
||||
- Also applied when: `Component/Frontend` or `Component/UI` label is present
|
||||
- Example: "Create new neighbourhood comparison dashboard tab"
|
||||
|
||||
**Domain/Data:**
|
||||
- Keywords: "schema", "migration", "pipeline", "dbt", "table", "column", "query", "PostgreSQL", "lineage", "data model"
|
||||
- Also applied when: `Component/Database` or `Component/Data` label is present
|
||||
- Example: "Add census demographic data pipeline"
|
||||
|
||||
## Label Suggestion Logic
|
||||
|
||||
When suggesting labels for issues, consider the following patterns:
|
||||
|
||||
@@ -1,288 +0,0 @@
|
||||
---
|
||||
agent: design-reviewer
|
||||
description: Reviews code for design system compliance using viz-platform MCP tools
|
||||
triggers:
|
||||
- /design-review command
|
||||
- /design-gate command
|
||||
- projman orchestrator domain gate
|
||||
---
|
||||
|
||||
# Design Reviewer Agent
|
||||
|
||||
You are a strict design system compliance auditor. Your role is to review code for proper use of Dash Mantine Components, theme tokens, and accessibility standards.
|
||||
|
||||
## Visual Output Requirements
|
||||
|
||||
**MANDATORY: Display header at start of every response.**
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| VIZ-PLATFORM - Design Reviewer |
|
||||
| [Target Path] |
|
||||
+----------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Trigger Conditions
|
||||
|
||||
Activate this agent when:
|
||||
- User runs `/design-review <path>`
|
||||
- User runs `/design-gate <path>`
|
||||
- Projman orchestrator requests design domain gate check
|
||||
- Code review includes DMC/Dash components
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- skills/design-system-audit.md
|
||||
|
||||
## Available MCP Tools
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `validate_component` | Check DMC component configurations for invalid props |
|
||||
| `get_component_props` | Retrieve expected props for a component |
|
||||
| `list_components` | Cross-reference components against DMC registry |
|
||||
| `theme_validate` | Validate theme configuration |
|
||||
| `accessibility_validate_colors` | Verify color contrast meets WCAG standards |
|
||||
| `accessibility_validate_theme` | Full theme accessibility audit |
|
||||
|
||||
## Operating Modes
|
||||
|
||||
### Review Mode (default)
|
||||
|
||||
Triggered by `/design-review <path>`
|
||||
|
||||
**Characteristics:**
|
||||
- Produces detailed report with all findings
|
||||
- Groups findings by severity (FAIL/WARN/INFO)
|
||||
- Includes actionable recommendations with code fixes
|
||||
- Does NOT block - informational only
|
||||
- Shows theme compliance percentage
|
||||
|
||||
### Gate Mode
|
||||
|
||||
Triggered by `/design-gate <path>` or projman orchestrator domain gate
|
||||
|
||||
**Characteristics:**
|
||||
- Binary PASS/FAIL output
|
||||
- Only reports FAIL-level issues
|
||||
- Returns exit status for automation integration
|
||||
- Blocks completion on FAIL
|
||||
- Compact output for CI/CD pipelines
|
||||
|
||||
## Audit Workflow
|
||||
|
||||
### 1. Receive Target Path
|
||||
Accept file or directory path from command invocation.
|
||||
|
||||
### 2. Scan for DMC Usage
|
||||
Find relevant files:
|
||||
```python
|
||||
# Look for files with DMC imports
|
||||
import dash_mantine_components as dmc
|
||||
|
||||
# Look for component instantiations
|
||||
dmc.Button(...)
|
||||
dmc.Card(...)
|
||||
```
|
||||
|
||||
### 3. Component Validation
|
||||
For each DMC component found:
|
||||
|
||||
1. Extract component name and props from code
|
||||
2. Call `list_components` to verify component exists in registry
|
||||
3. Call `get_component_props` to get valid prop schema
|
||||
4. Compare used props against schema
|
||||
5. **FAIL**: Invalid props, unknown components
|
||||
6. **WARN**: Deprecated patterns, React-style props
|
||||
|
||||
### 4. Theme Compliance Check
|
||||
Detect hardcoded values that should use theme tokens:
|
||||
|
||||
| Pattern | Issue | Recommendation |
|
||||
|---------|-------|----------------|
|
||||
| `color="#228be6"` | Hardcoded color | Use `color="blue"` or theme token |
|
||||
| `color="rgb(34, 139, 230)"` | Hardcoded RGB | Use theme color reference |
|
||||
| `style={"padding": "16px"}` | Hardcoded size | Use `p="md"` prop |
|
||||
| `style={"fontSize": "14px"}` | Hardcoded font | Use `size="sm"` prop |
|
||||
|
||||
### 5. Accessibility Validation
|
||||
Check accessibility compliance:
|
||||
|
||||
1. Call `accessibility_validate_colors` on detected color pairs
|
||||
2. Check color contrast ratios (min 4.5:1 for AA)
|
||||
3. Verify interactive components have accessible labels
|
||||
4. Flag missing aria-labels on buttons/links
|
||||
|
||||
### 6. Generate Report
|
||||
Output format depends on operating mode.
|
||||
|
||||
## Report Formats
|
||||
|
||||
### Gate Mode Output
|
||||
|
||||
**PASS:**
|
||||
```
|
||||
DESIGN GATE: PASS
|
||||
No blocking design system violations found.
|
||||
```
|
||||
|
||||
**FAIL:**
|
||||
```
|
||||
DESIGN GATE: FAIL
|
||||
|
||||
Blocking Issues (2):
|
||||
1. app/pages/home.py:45 - Invalid prop 'onclick' on dmc.Button
|
||||
Fix: Use 'n_clicks' for click handling
|
||||
|
||||
2. app/components/nav.py:12 - Component 'dmc.Navbar' not found
|
||||
Fix: Use 'dmc.AppShell.Navbar' (DMC v0.14+)
|
||||
|
||||
Run /design-review for full audit report.
|
||||
```
|
||||
|
||||
### Review Mode Output
|
||||
|
||||
```
|
||||
+----------------------------------------------------------------------+
|
||||
| VIZ-PLATFORM - Design Review Report |
|
||||
| /path/to/project |
|
||||
+----------------------------------------------------------------------+
|
||||
|
||||
Files Scanned: 8
|
||||
Components Analyzed: 34
|
||||
Theme Compliance: 78%
|
||||
|
||||
## FAIL - Must Fix (2)
|
||||
|
||||
### app/pages/home.py:45
|
||||
**Invalid prop on dmc.Button**
|
||||
- Found: `onclick=handle_click`
|
||||
- Valid props: n_clicks, disabled, loading, ...
|
||||
- Fix: `n_clicks` triggers callback, not `onclick`
|
||||
|
||||
### app/components/nav.py:12
|
||||
**Component not in registry**
|
||||
- Found: `dmc.Navbar`
|
||||
- Status: Removed in DMC v0.14
|
||||
- Fix: Use `dmc.AppShell.Navbar` instead
|
||||
|
||||
## WARN - Should Fix (3)
|
||||
|
||||
### app/pages/home.py:23
|
||||
**Hardcoded color**
|
||||
- Found: `color="#228be6"`
|
||||
- Recommendation: Use `theme.colors.blue[6]` or `color="blue"`
|
||||
|
||||
### app/components/card.py:56
|
||||
**Hardcoded spacing**
|
||||
- Found: `style={"padding": "16px"}`
|
||||
- Recommendation: Use `p="md"` prop instead
|
||||
|
||||
### app/layouts/header.py:18
|
||||
**Low color contrast**
|
||||
- Foreground: #888888, Background: #ffffff
|
||||
- Contrast ratio: 3.5:1 (below AA standard of 4.5:1)
|
||||
- Recommendation: Darken text to #757575 for 4.6:1 ratio
|
||||
|
||||
## INFO - Suggestions (2)
|
||||
|
||||
### app/components/card.py:8
|
||||
**Consider more specific component**
|
||||
- Found: `dmc.Box` used as card container
|
||||
- Suggestion: `dmc.Paper` provides card semantics and shadow
|
||||
|
||||
### app/pages/dashboard.py:92
|
||||
**Missing aria-label**
|
||||
- Found: `dmc.ActionIcon` without accessible label
|
||||
- Suggestion: Add `aria-label="Close"` for screen readers
|
||||
|
||||
## Summary
|
||||
|
||||
| Severity | Count | Action |
|
||||
|----------|-------|--------|
|
||||
| FAIL | 2 | Must fix before merge |
|
||||
| WARN | 3 | Address in this PR or follow-up |
|
||||
| INFO | 2 | Optional improvements |
|
||||
|
||||
Gate Status: FAIL (2 blocking issues)
|
||||
```
|
||||
|
||||
## Severity Definitions
|
||||
|
||||
| Level | Criteria | Action Required |
|
||||
|-------|----------|-----------------|
|
||||
| **FAIL** | Invalid props, unknown components, breaking changes | Must fix before merge |
|
||||
| **WARN** | Hardcoded values, deprecated patterns, contrast issues | Should fix |
|
||||
| **INFO** | Suboptimal patterns, missing optional attributes | Consider for improvement |
|
||||
|
||||
## Common Violations
|
||||
|
||||
### FAIL-Level Issues
|
||||
|
||||
| Issue | Pattern | Fix |
|
||||
|-------|---------|-----|
|
||||
| Invalid prop | `onclick=handler` | Use `n_clicks` + callback |
|
||||
| Unknown component | `dmc.Navbar` | Use `dmc.AppShell.Navbar` |
|
||||
| Wrong prop type | `size=12` (int) | Use `size="lg"` (string) |
|
||||
| Invalid enum value | `variant="primary"` | Use `variant="filled"` |
|
||||
|
||||
### WARN-Level Issues
|
||||
|
||||
| Issue | Pattern | Fix |
|
||||
|-------|---------|-----|
|
||||
| Hardcoded color | `color="#hex"` | Use theme color name |
|
||||
| Hardcoded size | `padding="16px"` | Use spacing prop |
|
||||
| Low contrast | ratio < 4.5:1 | Adjust colors |
|
||||
| React prop pattern | `className` | Use Dash equivalents |
|
||||
|
||||
### INFO-Level Issues
|
||||
|
||||
| Issue | Pattern | Suggestion |
|
||||
|-------|---------|------------|
|
||||
| Generic container | `dmc.Box` for cards | Use `dmc.Paper` |
|
||||
| Missing aria-label | Interactive without label | Add accessible name |
|
||||
| Inline styles | `style={}` overuse | Use component props |
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Response |
|
||||
|-------|----------|
|
||||
| MCP server unavailable | Report error, suggest checking viz-platform MCP setup |
|
||||
| No DMC files found | "No Dash Mantine Components detected in target path" |
|
||||
| Invalid path | "Path not found: {path}" |
|
||||
| Empty directory | "No Python files found in {path}" |
|
||||
|
||||
## Integration with Projman
|
||||
|
||||
When called as a domain gate by projman orchestrator:
|
||||
|
||||
1. Receive path from orchestrator
|
||||
2. Run audit in gate mode
|
||||
3. Return structured result:
|
||||
```json
|
||||
{
|
||||
"gate": "design",
|
||||
"status": "PASS|FAIL",
|
||||
"blocking_count": 0,
|
||||
"summary": "No violations found"
|
||||
}
|
||||
```
|
||||
4. Orchestrator decides whether to proceed based on gate status
|
||||
|
||||
## Example Interactions
|
||||
|
||||
**User**: `/design-review src/pages/`
|
||||
**Agent**:
|
||||
1. Scans all .py files in src/pages/
|
||||
2. Identifies DMC component usage
|
||||
3. Validates each component with MCP tools
|
||||
4. Checks theme token usage
|
||||
5. Runs accessibility validation
|
||||
6. Returns full review report
|
||||
|
||||
**User**: `/design-gate src/`
|
||||
**Agent**:
|
||||
1. Scans all .py files
|
||||
2. Identifies FAIL-level issues only
|
||||
3. Returns PASS if clean, FAIL with blocking issues if not
|
||||
4. Compact output for pipeline integration
|
||||
@@ -1,93 +0,0 @@
|
||||
---
|
||||
description: Design system compliance gate (pass/fail) for sprint execution
|
||||
arguments:
|
||||
- name: path
|
||||
description: File or directory to validate
|
||||
required: true
|
||||
---
|
||||
|
||||
# /design-gate
|
||||
|
||||
Binary pass/fail validation for design system compliance. Used by projman orchestrator during sprint execution to gate issue completion.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/design-gate <path>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/design-gate ./app/pages/dashboard.py
|
||||
/design-gate ./app/components/
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
1. **Activates** the `design-reviewer` agent in gate mode
|
||||
2. **Loads** the `skills/design-system-audit.md` skill
|
||||
3. **Scans** target path for DMC usage
|
||||
4. **Checks only for FAIL-level violations:**
|
||||
- Invalid component props
|
||||
- Non-existent components
|
||||
- Missing required props
|
||||
- Deprecated components
|
||||
5. **Returns binary result:**
|
||||
- `PASS` - No blocking violations found
|
||||
- `FAIL` - One or more blocking violations
|
||||
|
||||
## Output
|
||||
|
||||
### On PASS
|
||||
```
|
||||
DESIGN GATE: PASS
|
||||
No blocking design system violations found.
|
||||
```
|
||||
|
||||
### On FAIL
|
||||
```
|
||||
DESIGN GATE: FAIL
|
||||
|
||||
Blocking Issues (2):
|
||||
1. app/pages/home.py:45 - Invalid prop 'onclick' on dmc.Button
|
||||
Fix: Use 'n_clicks' for click handling
|
||||
|
||||
2. app/components/nav.py:12 - Component 'dmc.Navbar' not found
|
||||
Fix: Use 'dmc.AppShell.Navbar' (DMC v0.14+)
|
||||
|
||||
Run /design-review for full audit report.
|
||||
```
|
||||
|
||||
## Integration with projman
|
||||
|
||||
This command is automatically invoked by the projman orchestrator when:
|
||||
|
||||
1. An issue has the `Domain/Viz` label
|
||||
2. The orchestrator is about to mark the issue as complete
|
||||
3. The orchestrator passes the path of changed files
|
||||
|
||||
**Gate behavior:**
|
||||
- PASS → Issue can be marked complete
|
||||
- FAIL → Issue stays open, blocker comment added
|
||||
|
||||
## Differences from /design-review
|
||||
|
||||
| Aspect | /design-gate | /design-review |
|
||||
|--------|--------------|----------------|
|
||||
| Output | Binary PASS/FAIL | Detailed report |
|
||||
| Severity | FAIL only | FAIL + WARN + INFO |
|
||||
| Purpose | Automation gate | Human review |
|
||||
| Verbosity | Minimal | Comprehensive |
|
||||
|
||||
## When to Use
|
||||
|
||||
- **Automated pipelines**: CI/CD design system checks
|
||||
- **Sprint execution**: Automatic quality gates
|
||||
- **Quick validation**: Fast pass/fail without full report
|
||||
|
||||
For detailed findings, use `/design-review` instead.
|
||||
|
||||
## Requirements
|
||||
|
||||
- viz-platform MCP server must be running
|
||||
- Target path must exist
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
description: Audit codebase for design system compliance
|
||||
arguments:
|
||||
- name: path
|
||||
description: File or directory to audit
|
||||
required: true
|
||||
---
|
||||
|
||||
# /design-review
|
||||
|
||||
Scans target path for Dash Mantine Components usage and validates against design system standards.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/design-review <path>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
/design-review ./app/pages/
|
||||
/design-review ./app/components/dashboard.py
|
||||
/design-review .
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
1. **Activates** the `design-reviewer` agent in review mode
|
||||
2. **Loads** the `skills/design-system-audit.md` skill
|
||||
3. **Scans** target path for:
|
||||
- Python files with DMC imports
|
||||
- Component instantiations and their props
|
||||
- Style dictionaries and color values
|
||||
- Accessibility attributes
|
||||
4. **Validates** against:
|
||||
- DMC component registry (valid components and props)
|
||||
- Theme token usage (no hardcoded colors/sizes)
|
||||
- Accessibility standards (contrast, ARIA labels)
|
||||
5. **Produces** detailed report grouped by severity
|
||||
|
||||
## Output
|
||||
|
||||
Generates a comprehensive audit report with:
|
||||
|
||||
- **FAIL**: Invalid props, deprecated components, missing required props
|
||||
- **WARN**: Hardcoded colors/sizes, missing accessibility attributes
|
||||
- **INFO**: Optimization suggestions, consistency recommendations
|
||||
|
||||
Each finding includes:
|
||||
- File path and line number
|
||||
- Description of the issue
|
||||
- Recommended fix
|
||||
|
||||
## When to Use
|
||||
|
||||
- **Before PR review**: Catch design system violations early
|
||||
- **On existing codebases**: Audit for compliance gaps
|
||||
- **During refactoring**: Ensure changes maintain compliance
|
||||
- **Learning**: Understand design system best practices
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/design-gate` - Binary pass/fail for sprint execution (no detailed report)
|
||||
- `/component` - Inspect individual DMC component props
|
||||
- `/theme` - Check active theme configuration
|
||||
|
||||
## Requirements
|
||||
|
||||
- viz-platform MCP server must be running
|
||||
- Target path must contain Python files with DMC usage
|
||||
@@ -1,280 +0,0 @@
|
||||
---
|
||||
name: design-system-audit
|
||||
description: Design system compliance rules and violation patterns for viz-platform audits
|
||||
---
|
||||
|
||||
# Design System Audit
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines what to check, how to classify violations, and common patterns for design system compliance auditing of Dash Mantine Components (DMC) code.
|
||||
|
||||
---
|
||||
|
||||
## What to Check
|
||||
|
||||
### 1. Component Prop Validity
|
||||
|
||||
| Check | Tool | Severity |
|
||||
|-------|------|----------|
|
||||
| Invalid prop names (typos) | `validate_component` | FAIL |
|
||||
| Invalid prop values | `validate_component` | FAIL |
|
||||
| Missing required props | `validate_component` | FAIL |
|
||||
| Deprecated props | `get_component_props` | WARN |
|
||||
| Unknown props | `validate_component` | WARN |
|
||||
|
||||
### 2. Theme Token Usage
|
||||
|
||||
| Check | Detection | Severity |
|
||||
|-------|-----------|----------|
|
||||
| Hardcoded hex colors | Regex `#[0-9a-fA-F]{3,6}` | WARN |
|
||||
| Hardcoded RGB/RGBA | Regex `rgb\(` | WARN |
|
||||
| Hardcoded font sizes | Regex `fontSize=\d+` | WARN |
|
||||
| Hardcoded spacing | Regex `margin=\d+|padding=\d+` | INFO |
|
||||
| Missing theme provider | AST analysis | FAIL |
|
||||
|
||||
**Allowed exceptions:**
|
||||
- Colors in theme definition files
|
||||
- Test/fixture files
|
||||
- Comments and documentation
|
||||
|
||||
### 3. Accessibility Compliance
|
||||
|
||||
| Check | Tool | Severity |
|
||||
|-------|------|----------|
|
||||
| Color contrast ratio < 4.5:1 (AA) | `accessibility_validate_colors` | WARN |
|
||||
| Color contrast ratio < 3:1 (large text) | `accessibility_validate_colors` | WARN |
|
||||
| Missing aria-label on interactive | Manual scan | WARN |
|
||||
| Color-only information | `accessibility_validate_theme` | WARN |
|
||||
| Focus indicator missing | Manual scan | INFO |
|
||||
|
||||
### 4. Responsive Design
|
||||
|
||||
| Check | Detection | Severity |
|
||||
|-------|-----------|----------|
|
||||
| Fixed pixel widths > 600px | Regex `width=\d{3,}` | INFO |
|
||||
| Missing breakpoint handling | No `visibleFrom`/`hiddenFrom` | INFO |
|
||||
| Non-responsive layout | Fixed Grid columns | INFO |
|
||||
|
||||
---
|
||||
|
||||
## Common Violations
|
||||
|
||||
### FAIL-Level Violations
|
||||
|
||||
```python
|
||||
# Invalid prop name (typo)
|
||||
dmc.Button(colour="blue") # Should be 'color'
|
||||
|
||||
# Invalid enum value
|
||||
dmc.Button(size="large") # Should be 'lg'
|
||||
|
||||
# Missing required prop
|
||||
dmc.Select(data=[...]) # Missing 'id' for callbacks
|
||||
|
||||
# Invalid component name
|
||||
dmc.Buttons(...) # Should be 'Button'
|
||||
|
||||
# Wrong case
|
||||
dmc.Button(fullwidth=True) # Should be 'fullWidth'
|
||||
|
||||
# React patterns in Dash
|
||||
dmc.Button(onClick=fn) # Should use 'id' + callback
|
||||
```
|
||||
|
||||
### WARN-Level Violations
|
||||
|
||||
```python
|
||||
# Hardcoded colors
|
||||
dmc.Text(color="#ff0000") # Use theme token
|
||||
dmc.Button(style={"color": "red"}) # Use theme token
|
||||
|
||||
# Hardcoded font size
|
||||
dmc.Text(style={"fontSize": "14px"}) # Use 'size' prop
|
||||
|
||||
# Poor contrast
|
||||
dmc.Text(color="gray") # Check contrast ratio
|
||||
|
||||
# Inline styles for colors
|
||||
dmc.Container(style={"backgroundColor": "#f0f0f0"})
|
||||
|
||||
# Deprecated patterns
|
||||
dmc.Button(variant="subtle") # Check if still supported
|
||||
```
|
||||
|
||||
### INFO-Level Violations
|
||||
|
||||
```python
|
||||
# Fixed widths
|
||||
dmc.Container(w=800) # Consider responsive
|
||||
|
||||
# Missing responsive handling
|
||||
dmc.Grid.Col(span=6) # Consider span={{ base: 12, md: 6 }}
|
||||
|
||||
# Optimization opportunity
|
||||
dmc.Stack([dmc.Text(...) for _ in range(100)]) # Consider virtualization
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Severity Classification
|
||||
|
||||
| Level | Icon | Meaning | Action |
|
||||
|-------|------|---------|--------|
|
||||
| **FAIL** | Red circle | Blocking issue, will cause runtime error | Must fix before completion |
|
||||
| **WARN** | Orange circle | Quality issue, violates best practices | Should fix, may be waived |
|
||||
| **INFO** | Yellow circle | Suggestion for improvement | Consider for future |
|
||||
|
||||
### Severity Decision Tree
|
||||
|
||||
```
|
||||
Is it invalid syntax/props?
|
||||
YES -> FAIL
|
||||
NO -> Does it violate accessibility standards?
|
||||
YES -> WARN
|
||||
NO -> Does it use hardcoded styles?
|
||||
YES -> WARN
|
||||
NO -> Is it a best practice suggestion?
|
||||
YES -> INFO
|
||||
NO -> Not a violation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scanning Strategy
|
||||
|
||||
### File Types to Scan
|
||||
|
||||
| Extension | Priority | Check For |
|
||||
|-----------|----------|-----------|
|
||||
| `*.py` | High | DMC component usage |
|
||||
| `*.dash.py` | High | Layout definitions |
|
||||
| `theme*.py` | High | Theme configuration |
|
||||
| `layout*.py` | High | Layout structure |
|
||||
| `components/*.py` | High | Custom components |
|
||||
| `callbacks/*.py` | Medium | Component references |
|
||||
|
||||
### Scan Process
|
||||
|
||||
1. **Find relevant files**
|
||||
```
|
||||
glob: **/*.py
|
||||
filter: Contains 'dmc.' or 'dash_mantine_components'
|
||||
```
|
||||
|
||||
2. **Extract component usages**
|
||||
- Parse Python AST
|
||||
- Find all `dmc.*` calls
|
||||
- Extract component name and kwargs
|
||||
|
||||
3. **Validate each component**
|
||||
- Call `validate_component(name, props)`
|
||||
- Record violations with file:line reference
|
||||
|
||||
4. **Scan for patterns**
|
||||
- Hardcoded colors (regex)
|
||||
- Inline styles (AST)
|
||||
- Fixed dimensions (regex)
|
||||
|
||||
5. **Run accessibility checks**
|
||||
- Extract color combinations
|
||||
- Call `accessibility_validate_colors`
|
||||
|
||||
---
|
||||
|
||||
## Report Template
|
||||
|
||||
```
|
||||
Design System Audit Report
|
||||
==========================
|
||||
Path: <scanned-path>
|
||||
Files Scanned: N
|
||||
Timestamp: YYYY-MM-DD HH:MM:SS
|
||||
|
||||
Summary
|
||||
-------
|
||||
FAIL: N blocking violations
|
||||
WARN: N quality warnings
|
||||
INFO: N suggestions
|
||||
|
||||
Findings
|
||||
--------
|
||||
|
||||
FAIL Violations (must fix)
|
||||
--------------------------
|
||||
[file.py:42] Invalid prop 'colour' on Button
|
||||
Found: colour="blue"
|
||||
Expected: color="blue"
|
||||
Docs: https://mantine.dev/core/button
|
||||
|
||||
[file.py:58] Invalid size value on Text
|
||||
Found: size="huge"
|
||||
Expected: One of ['xs', 'sm', 'md', 'lg', 'xl']
|
||||
|
||||
WARN Violations (should fix)
|
||||
----------------------------
|
||||
[theme.py:15] Hardcoded color detected
|
||||
Found: color="#ff0000"
|
||||
Suggestion: Use theme color token (e.g., color="red")
|
||||
|
||||
[layout.py:23] Low contrast ratio (3.2:1)
|
||||
Found: Text on background
|
||||
Required: 4.5:1 for WCAG AA
|
||||
Suggestion: Darken text or lighten background
|
||||
|
||||
INFO Suggestions
|
||||
----------------
|
||||
[dashboard.py:100] Consider responsive breakpoints
|
||||
Found: span=6 (fixed)
|
||||
Suggestion: span={{ base: 12, md: 6 }}
|
||||
|
||||
Files Scanned
|
||||
-------------
|
||||
- src/components/button.py (3 components)
|
||||
- src/layouts/main.py (8 components)
|
||||
- src/theme.py (1 theme config)
|
||||
|
||||
Gate Result: PASS | FAIL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with MCP Tools
|
||||
|
||||
### Required Tools
|
||||
|
||||
| Tool | Purpose | When Used |
|
||||
|------|---------|-----------|
|
||||
| `validate_component` | Check component props | Every component found |
|
||||
| `get_component_props` | Get expected props | When suggesting fixes |
|
||||
| `list_components` | Verify component exists | Unknown component names |
|
||||
| `theme_validate` | Validate theme config | Theme files |
|
||||
| `accessibility_validate_colors` | Check contrast | Color combinations |
|
||||
| `accessibility_validate_theme` | Full a11y audit | Theme files |
|
||||
|
||||
### Tool Call Pattern
|
||||
|
||||
```
|
||||
For each Python file:
|
||||
For each dmc.Component(...) found:
|
||||
result = validate_component(
|
||||
component_name="Component",
|
||||
props={extracted_props}
|
||||
)
|
||||
if result.errors:
|
||||
record FAIL violation
|
||||
if result.warnings:
|
||||
record WARN violation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skip Patterns
|
||||
|
||||
Do not flag violations in:
|
||||
|
||||
- `**/tests/**` - Test files may have intentional violations
|
||||
- `**/__pycache__/**` - Compiled files
|
||||
- `**/fixtures/**` - Test fixtures
|
||||
- Files with `# noqa: design-audit` comment
|
||||
- Theme definition files (colors are expected there)
|
||||
Reference in New Issue
Block a user