Compliance Check Skill

Verify and enforce coding standards, AI guidelines, and workspace compliance across all 26+ repositories.

Quick Start

Quick compliance check

./scripts/compliance/verify_compliance.sh

Check specific repository

./scripts/compliance/verify_compliance.sh --repo=digitalmodel

Propagate standards to all repos

./scripts/compliance/propagate_claude_config.py

When to Use

Setting up a new repository that needs workspace standards
Verifying all repos meet coding and documentation standards
Propagating updated guidelines across the workspace
Installing pre-commit hooks for enforcement
Auditing compliance before releases

Prerequisites

Access to workspace-hub compliance scripts
Write access to target repositories
Python 3.x for propagation scripts
Git for hook installation

Overview

This skill ensures consistent coding standards, AI usage guidelines, and development practices across all workspace-hub repositories. It covers verification, propagation, and enforcement of compliance requirements.

Compliance Areas

AI Agent Guidelines

Ensure AI agents follow required workflows:

Read user_prompt.md before implementation
Ask clarifying questions
Wait for user approval
Follow SPARC methodology
Use TDD practices

Reference: AI_AGENT_GUIDELINES.md

Development Workflow

Ensure proper workflow adherence:

user_prompt.md -> YAML config -> Pseudocode -> TDD -> Implementation
Bash-based execution
Interactive engagement
Gate-pass reviews

Reference: DEVELOPMENT_WORKFLOW.md

File Organization

Ensure proper directory structure:

/src
Source code
/tests
Test files
/docs
Documentation
/config
Configuration
/scripts
Utility scripts
/data
Data files
/reports
Generated reports

Reference: FILE_ORGANIZATION_STANDARDS.md

Code Quality Standards

Ensure code meets quality requirements:

80%+ test coverage
Proper logging (5 levels)
HTML reports with interactive plots
No static matplotlib exports

References:

TESTING_FRAMEWORK_STANDARDS.md
LOGGING_STANDARDS.md
HTML_REPORTING_STANDARDS.md

Verification Commands

Quick Compliance Check

./scripts/compliance/verify_compliance.sh

Check Specific Repository

./scripts/compliance/verify_compliance.sh --repo=digitalmodel

Check Specific Area

./scripts/compliance/verify_compliance.sh --area=testing ./scripts/compliance/verify_compliance.sh --area=logging ./scripts/compliance/verify_compliance.sh --area=file-org

Execution Checklist

Run full compliance scan on all repos
Review compliance report for failures
Fix critical compliance issues first
Propagate standards to non-compliant repos
Install git hooks for enforcement
Verify CI/CD integration
Document any approved exceptions

Compliance Verification Checklists

Repository Structure

Structure Compliance

/src directory exists and contains source code
/tests directory exists with unit and integration tests
/docs directory exists with documentation
/config directory exists for configurations
/scripts directory exists for utilities
No files in root (except standard config files)
CLAUDE.md exists and follows template
.agent-os/ directory properly configured

Testing Standards

Testing Compliance

pytest configured as test framework
Test coverage >= 80%
Unit tests in /tests/unit/
Integration tests in /tests/integration/
No mock data (use real repository data)
Performance tests exist
Tests run in CI/CD pipeline

Logging Standards

Logging Compliance

All 5 log levels supported (DEBUG, INFO, WARNING, ERROR, CRITICAL)
Standard log format used
Log files in /logs directory
Log rotation configured
Sensitive data sanitized
Structured logging for parsing

HTML Reporting

Reporting Compliance

HTML reports generated (not static images)
Interactive plots (Plotly, Bokeh, Altair)
No matplotlib PNG exports
CSV data uses relative paths
Reports in /reports directory
Responsive design

AI Guidelines

AI Compliance

CLAUDE.md references AI_AGENT_GUIDELINES.md
Interactive engagement enforced
Question-asking pattern documented
TDD workflow required
No assumptions without clarification

Propagation Tools

Propagate CLAUDE.md Configuration

./scripts/compliance/propagate_claude_config.py

Syncs CLAUDE.md template to all repositories.

Propagate AI Guidelines

./scripts/compliance/propagate_guidelines.sh

Updates AI_AGENT_GUIDELINES.md and AI_USAGE_GUIDELINES.md.

Propagate Interactive Mode

./scripts/compliance/propagate_interactive_mode.sh

Ensures interactive engagement rules are in place.

Git Hooks for Enforcement

Install Compliance Hooks

./scripts/compliance/install_compliance_hooks.sh

Pre-commit Hook Checks

The pre-commit hook verifies:

File organization: No files in wrong locations
Test coverage: Coverage report exists and meets threshold
Linting: No syntax errors
YAML validation: Valid YAML configuration
Documentation: Required docs exist

Hook Configuration

.git/hooks/pre-commit

#!/bin/bash set -e

echo "Running compliance checks..."

Check file organization

./scripts/compliance/check_file_org.sh

Check test coverage

coverage=$(./scripts/compliance/get_coverage.sh) if [ "$coverage" -lt 80 ]; then echo "ERROR: Test coverage $coverage% is below 80%" exit 1 fi

Check for static images in reports

if find reports/ -name ".png" -o -name ".jpg" | grep -q .; then echo "ERROR: Static images found in reports. Use interactive HTML." exit 1 fi

echo "Compliance checks passed!"

Error Handling

Common Compliance Failures

Issue Cause Resolution

Structure violation Files in wrong directory Move files to correct location

Low test coverage Insufficient tests Add unit/integration tests

Static images matplotlib exports Convert to Plotly/Bokeh HTML

Missing CLAUDE.md New repo setup Run propagation script

Hook not running Permission issue chmod +x .git/hooks/pre-commit

Fixing Non-Compliance

Structure Issues

Create missing directories

mkdir -p src tests docs config scripts data reports logs

Move misplaced files

git mv root_file.py src/ git mv old_tests.py tests/unit/

Testing Issues

Install pytest and coverage

pip install pytest pytest-cov

Run tests with coverage

pytest --cov=src --cov-report=html --cov-fail-under=80

Logging Issues

Add proper logging configuration

import logging

logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - [%(filename)s:%(lineno)d] - %(message)s', handlers=[ logging.FileHandler('logs/app.log'), logging.StreamHandler() ] )

Reporting Issues

Replace matplotlib with Plotly

Before (non-compliant):

import matplotlib.pyplot as plt plt.savefig('reports/chart.png')

After (compliant):

import plotly.express as px fig = px.line(df, x='x', y='y') fig.write_html('reports/chart.html')

Troubleshooting

Hook Not Running

Make hook executable

chmod +x .git/hooks/pre-commit

Check hook exists

ls -la .git/hooks/pre-commit

False Positives

Add exceptions to compliance config

config/compliance.yaml

exceptions:

path: legacy/old_module.py reason: "Legacy code, scheduled for refactoring in Q2"

Coverage Not Detected

Ensure coverage config exists

pyproject.toml or .coveragerc

[tool.coverage.run] source = ["src"] omit = ["tests/", "/migrations/*"]

Metrics & Success Criteria

Compliance Rate: >= 95% of repos fully compliant
Propagation Success: 100% of repos have latest standards
Hook Coverage: Git hooks installed in all active repos
CI Integration: All repos have compliance in CI/CD
Exception Rate: < 5% of checks have documented exceptions

Compliance Reports

Generate Compliance Report

./scripts/compliance/generate_report.sh > reports/compliance_report.html

Report Template

<!DOCTYPE html> <html> <head> <title>Compliance Report</title> <style> .pass { color: green; } .fail { color: red; } .warn { color: orange; } </style> </head> <body> <h1>Workspace Compliance Report</h1> <p>Generated: {{timestamp}}</p>

&#x3C;h2>Summary&#x3C;/h2>
&#x3C;table>
    &#x3C;tr>&#x3C;td>Total Repositories&#x3C;/td>&#x3C;td>{{total}}&#x3C;/td>&#x3C;/tr>
    &#x3C;tr>&#x3C;td class="pass">Fully Compliant&#x3C;/td>&#x3C;td>{{compliant}}&#x3C;/td>&#x3C;/tr>
    &#x3C;tr>&#x3C;td class="warn">Partial Compliance&#x3C;/td>&#x3C;td>{{partial}}&#x3C;/td>&#x3C;/tr>
    &#x3C;tr>&#x3C;td class="fail">Non-Compliant&#x3C;/td>&#x3C;td>{{non_compliant}}&#x3C;/td>&#x3C;/tr>
&#x3C;/table>

&#x3C;h2>Repository Details&#x3C;/h2>
{{#each repositories}}
&#x3C;h3>{{name}}&#x3C;/h3>
&#x3C;ul>
    {{#each checks}}
    &#x3C;li class="{{status}}">{{check}}: {{message}}&#x3C;/li>
    {{/each}}
&#x3C;/ul>
{{/each}}

</body> </html>

Automation

CI/CD Integration

.github/workflows/compliance.yml

name: Compliance Check

on: [push, pull_request]

jobs: compliance: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3

  - name: Check File Organization
    run: ./scripts/compliance/check_file_org.sh

  - name: Check Test Coverage
    run: |
      pip install pytest pytest-cov
      pytest --cov=src --cov-fail-under=80

  - name: Check for Static Images
    run: |
      if find reports/ -name "*.png" | grep -q .; then
        echo "Static images found in reports"
        exit 1
      fi

  - name: Validate YAML Configs
    run: ./scripts/compliance/validate_yaml.sh

Scheduled Compliance Scan

Run weekly compliance scan

name: Weekly Compliance Scan

on: schedule: - cron: '0 9 * * 1' # Monday 9am

jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Full Compliance Scan run: ./scripts/compliance/full_scan.sh - name: Upload Report uses: actions/upload-artifact@v3 with: name: compliance-report path: reports/compliance_report.html

Integration Points

With Repository Sync

After pulling, verify compliance

./scripts/repository_sync pull all ./scripts/compliance/verify_compliance.sh

With AI Agents

AI agents should:

Check compliance status before making changes
Maintain compliance during modifications
Report compliance issues found during work
Follow guidelines in CLAUDE.md

Related Skills

repo-sync - Repository management
sparc-workflow - Development methodology
workspace-cli - Unified CLI interface

Best Practices

For Repository Maintainers

Run compliance checks before commits
Fix issues immediately - don't accumulate debt
Use pre-commit hooks for automatic enforcement
Review compliance reports weekly

For AI Agents

Always check compliance status before making changes
Maintain compliance during modifications
Report compliance issues found during work
Follow guidelines in CLAUDE.md and referenced docs

For the Team

Standardize across repos using propagation tools
Monitor compliance trends over time
Address root causes not just symptoms
Document exceptions in decisions.md

References

AI Agent Guidelines
Development Workflow
File Organization Standards
Testing Standards
Logging Standards
HTML Reporting Standards

Version History

1.1.0 (2026-01-02): Upgraded to SKILL_TEMPLATE_v2 format - added Quick Start, When to Use, Execution Checklist, Error Handling consolidation, Metrics, Integration Points
1.0.0 (2024-10-15): Initial release with compliance verification, propagation tools, git hooks, CI/CD integration, troubleshooting

compliance-check

Safety Notice

Copy this and send it to your AI assistant to learn