Agent skill

moai-tag-policy-validator

Comprehensive TAG system validator and policy enforcer that monitors, validates, and corrects TAG usage across code, tests, and documentation. Use when ensuring TAG compliance, validating TAG policy violations, analyzing TAG coverage, or when maintaining TAG system integrity and governance.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/moai-tag-policy-validator

SKILL.md

TAG Policy Validator and Governance System

Skill Metadata

Field Value
Version 1.0.0
Tier Alfred (TAG System)
Auto-load When TAG violations detected or on demand
Purpose Ensure TAG system integrity and policy compliance

What It Does

Comprehensive TAG system validator and policy enforcer that monitors TAG usage, validates compliance with TAG policies, analyzes coverage, and provides automatic corrections for TAG violations. Ensures the integrity and governance of the MoAI-ADK TAG system.

Core capabilities:

  • ✅ Real-time TAG policy validation and enforcement
  • ✅ TAG coverage analysis across code, tests, and documentation
  • ✅ Automatic TAG violation detection and correction
  • ✅ TAG policy compliance reporting and metrics
  • ✅ Orphaned TAG detection and resolution
  • ✅ TAG chain integrity verification (SPEC→TEST→CODE→DOC)
  • ✅ TAG policy governance and rule management
  • ✅ TAG system health monitoring and alerts

When to Use

  • ✅ When validating TAG policy compliance
  • ✅ Before committing changes with TAG modifications
  • ✅ During code reviews and quality assurance
  • ✅ When analyzing TAG coverage and completeness
  • ✅ For TAG system maintenance and governance
  • ✅ When troubleshooting TAG-related issues
  • ✅ Before major releases or deployments

TAG Policy Framework

1. TAG Policy Rules

python
TAG_POLICIES = {
    "SPEC_TAGS": {
        "required_fields": ["id", "version", "status", "created", "updated", "author", "priority"],
        "format_validation": {
            "id": r"SPEC-[0-9]{3}",
            "version": r"[0-9]+\.[0-9]+\.[0-9]+",
            "status": r"^(draft|active|completed|archived)$"
        },
        "content_validation": {
            "min_content_length": 100,
            "required_sections": ["## What It Does", "## When to Use"],
            "max_content_lines": 500
        }
    },
    "CODE_TAGS": {
        "placement_rules": {
            "function_comments": True,
            "class_documentation": True,
            "module_level": True
        },
        "content_requirements": {
            "min_description_length": 20,
            "require_examples": True,
            "require_parameters": True
        }
    },
    "TEST_TAGS": {
        "coverage_requirements": {
            "test_function_tagging": True,
            "test_class_tagging": True,
            "parameter_testing": True
        },
        "content_validation": {
            "require_test_description": True,
            "require_expected_behavior": True
        }
    },
    "DOC_TAGS": {
        "linking_rules": {
            "bidirectional_links": True,
            "chain_completeness": True,
            "no_broken_links": True
        },
        "content_requirements": {
            "up_to_date": True,
            "accuracy_check": True,
            "completeness_check": True
        }
    }
}

2. TAG Chain Validation

python
def validate_tag_chains():
    """Validate complete TAG chains: SPEC → TEST → CODE → DOC"""
    chain_analysis = {
        "complete_chains": [],
        "broken_chains": [],
        "missing_links": [],
        "orphaned_tags": []
    }

    # Find all SPEC tags
    spec_tags = find_all_tags("SPEC-")

    for spec_tag in spec_tags:
        chain = {
            "spec": spec_tag,
            "tests": find_linked_tests(spec_tag),
            "code": find_linked_code(spec_tag),
            "docs": find_linked_docs(spec_tag)
        }

        # Validate chain completeness
        if is_complete_chain(chain):
            chain_analysis["complete_chains"].append(chain)
        else:
            missing = identify_missing_links(chain)
            chain_analysis["broken_chains"].append({
                "spec": spec_tag,
                "missing_links": missing,
                "severity": assess_chain_severity(missing)
            })

    return chain_analysis

3. TAG Coverage Analysis

python
def analyze_tag_coverage():
    """Analyze TAG coverage across project"""
    coverage_metrics = {
        "total_functions": count_functions(),
        "tagged_functions": count_tagged_functions(),
        "total_classes": count_classes(),
        "tagged_classes": count_tagged_classes(),
        "total_tests": count_tests(),
        "tagged_tests": count_tagged_tests(),
        "total_docs": count_documentation_files(),
        "tagged_docs": count_tagged_docs(),
        "coverage_percentages": {},
        "untagged_areas": []
    }

    # Calculate coverage percentages
    coverage_metrics["coverage_percentages"] = {
        "functions": (coverage_metrics["tagged_functions"] / coverage_metrics["total_functions"]) * 100,
        "classes": (coverage_metrics["tagged_classes"] / coverage_metrics["total_classes"]) * 100,
        "tests": (coverage_metrics["tagged_tests"] / coverage_metrics["total_tests"]) * 100,
        "docs": (coverage_metrics["tagged_docs"] / coverage_metrics["total_docs"]) * 100
    }

    # Identify untagged areas
    coverage_metrics["untagged_areas"] = find_untagged_areas()

    return coverage_metrics

Validation Engine

1. Real-time Validation

python
def validate_file_tags(file_path, file_content):
    """Validate TAGs in a specific file"""
    validation_result = {
        "file_path": file_path,
        "file_type": determine_file_type(file_path),
        "tags_found": extract_tags(file_content),
        "violations": [],
        "recommendations": [],
        "compliance_score": 0.0
    }

    # Extract and validate tags
    tags = extract_tags(file_content)

    for tag in tags:
        violations = validate_single_tag(tag, file_path)
        validation_result["violations"].extend(violations)

    # Calculate compliance score
    validation_result["compliance_score"] = calculate_compliance_score(
        validation_result["violations"], file_path
    )

    # Generate recommendations
    validation_result["recommendations"] = generate_recommendations(
        validation_result["violations"], file_path
    )

    return validation_result

2. Policy Violation Detection

python
def detect_policy_violations():
    """Detect all TAG policy violations in project"""
    violations = {
        "spec_violations": [],
        "code_violations": [],
        "test_violations": [],
        "doc_violations": [],
        "cross_file_violations": [],
        "policy_compliance": {}
    }

    # Scan all files for violations
    for file_path in get_all_project_files():
        file_violations = scan_file_for_violations(file_path)

        violation_type = categorize_violations(file_violations)
        violations[violation_type].extend(file_violations)

    # Check cross-file violations
    violations["cross_file_violations"] = check_cross_file_violations()

    # Calculate overall compliance
    violations["policy_compliance"] = calculate_overall_compliance(violations)

    return violations

3. Automatic Correction System

python
def auto_correct_violations(violations, dry_run=True):
    """Automatically correct TAG violations"""
    corrections_applied = []
    correction_failures = []

    for violation in violations:
        if violation.auto_correctable:
            try:
                correction = generate_correction(violation)

                if not dry_run:
                    apply_correction(correction)

                corrections_applied.append({
                    "violation": violation,
                    "correction": correction,
                    "status": "applied" if not dry_run else "preview"
                })

            except Exception as e:
                correction_failures.append({
                    "violation": violation,
                    "error": str(e),
                    "status": "failed"
                })

    return {
        "corrections_applied": corrections_applied,
        "correction_failures": correction_failures,
        "summary": generate_correction_summary(corrections_applied, correction_failures)
    }

TAG System Governance

1. Policy Management

python
def update_tag_policies(new_policies):
    """Update TAG policies with validation"""
    policy_update = {
        "timestamp": datetime.now().isoformat(),
        "old_policies": get_current_policies(),
        "new_policies": new_policies,
        "impact_analysis": analyze_policy_impact(new_policies),
        "validation_results": validate_new_policies(new_policies)
    }

    # Validate new policies
    if policy_update["validation_results"]["is_valid"]:
        apply_new_policies(new_policies)
        policy_update["status"] = "applied"
    else:
        policy_update["status"] = "rejected"
        policy_update["rejection_reasons"] = policy_update["validation_results"]["errors"]

    # Log policy changes
    log_policy_change(policy_update)

    return policy_update

2. Compliance Reporting

python
def generate_compliance_report():
    """Generate comprehensive TAG compliance report"""
    report = {
        "generated_at": datetime.now().isoformat(),
        "period": "last_7_days",
        "overall_compliance": 0.0,
        "coverage_metrics": analyze_tag_coverage(),
        "violation_summary": summarize_violations(),
        "trend_analysis": analyze_compliance_trends(),
        "recommendations": generate_compliance_recommendations(),
        "action_items": identify_action_items()
    }

    # Calculate overall compliance
    report["overall_compliance"] = calculate_overall_compliance_score(report)

    # Generate actionable insights
    report["insights"] = generate_compliance_insights(report)

    return report

3. Health Monitoring

python
def monitor_tag_system_health():
    """Monitor TAG system health and performance"""
    health_metrics = {
        "system_status": "healthy",
        "performance_metrics": {
            "validation_time": measure_validation_performance(),
            "correction_time": measure_correction_performance(),
            "scan_time": measure_scan_performance()
        },
        "quality_metrics": {
            "tag_accuracy": measure_tag_accuracy(),
            "link_integrity": measure_link_integrity(),
            "coverage_trend": measure_coverage_trend()
        },
        "alerts": [],
        "recommendations": []
    }

    # Check for health issues
    if health_metrics["quality_metrics"]["tag_accuracy"] < 0.9:
        health_metrics["alerts"].append({
            "severity": "warning",
            "message": "TAG accuracy below 90%",
            "recommendation": "Run validation and correction"
        })

    if health_metrics["quality_metrics"]["link_integrity"] < 0.85:
        health_metrics["alerts"].append({
            "severity": "error",
            "message": "TAG link integrity compromised",
            "recommendation": "Run TAG chain validation"
        })

    # Update system status
    health_metrics["system_status"] = determine_system_status(health_metrics["alerts"])

    return health_metrics

Integration Examples

Example 1: Pre-Commit Validation

python
def validate_tags_before_commit():
    """Validate TAGs before Git commit"""
    Skill("moai-tag-policy-validator")

    # Get staged files
    staged_files = get_staged_files()

    validation_results = []
    critical_violations = []

    for file_path in staged_files:
        result = validate_file_tags(file_path, read_file(file_path))
        validation_results.append(result)

        # Check for critical violations
        critical_violations.extend([
            v for v in result.violations if v.severity == "critical"
        ])

    if critical_violations:
        display_critical_violations(critical_violations)
        return False  # Block commit
    else:
        display_validation_summary(validation_results)
        return True  # Allow commit

Example 2: TAG Coverage Analysis

python
def analyze_project_tag_coverage():
    """Analyze TAG coverage across entire project"""
    Skill("moai-tag-policy-validator")

    coverage = analyze_tag_coverage()

    display_coverage_dashboard(coverage)

    # Identify areas needing attention
    low_coverage_areas = [
        area for area, coverage in coverage["coverage_percentages"].items()
        if coverage < 80
    ]

    if low_coverage_areas:
        display_coverage_gaps(low_coverage_areas)
        suggest_improvement_strategies(low_coverage_areas)

Example 3: Automatic Correction

python
def fix_tag_violations():
    """Fix TAG violations automatically"""
    Skill("moai-tag-policy-validator")

    violations = detect_policy_violations()
    auto_correctable = [v for v in violations if v.auto_correctable]

    if auto_correctable:
        print(f"Found {len(auto_correctable)} auto-correctable violations")

        # Preview corrections
        corrections = auto_correct_violations(auto_correctable, dry_run=True)
        display_correction_preview(corrections)

        # Ask for confirmation
        if confirm_corrections():
            # Apply corrections
            result = auto_correct_violations(auto_correctable, dry_run=False)
            display_correction_results(result)
    else:
        print("No auto-correctable violations found")

Quality Assurance

1. Validation Rules

python
VALIDATION_RULES = {
    "spec_format": {
        "required": ["@SPEC:ID", "@VERSION", "@STATUS"],
        "forbidden": ["@TODO", "@FIXME"],
        "patterns": {
            "@SPEC:": r"@[A-Z]+:[A-Z0-9-]+"
        }
    },
    "code_format": {
        "placement": ["function_level", "class_level", "module_level"],
        "content": ["description", "parameters", "returns"],
        "forbidden": ["vague_descriptions"]
    },
    "link_format": {
        "required": ["source", "target"],
        "bidirectional": True,
        "no_broken_links": True
    }
}

2. Quality Metrics

python
def calculate_tag_quality_metrics():
    """Calculate TAG quality metrics"""
    metrics = {
        "accuracy": measure_tag_accuracy(),
        "completeness": measure_tag_completeness(),
        "consistency": measure_tag_consistency(),
        "maintainability": measure_tag_maintainability(),
        "traceability": measure_tag_traceability()
    }

    # Calculate overall quality score
    metrics["overall_score"] = calculate_overall_quality_score(metrics)

    return metrics

3. Continuous Improvement

python
def improve_tag_system():
    """Continuously improve TAG system based on usage patterns"""
    improvement_plan = {
        "usage_analysis": analyze_tag_usage_patterns(),
        "feedback_integration": integrate_user_feedback(),
        "policy_refinement": refine_policies_based_on_data(),
        "tooling_enhancement": identify_tooling_improvements()
    }

    # Generate improvement recommendations
    recommendations = generate_improvement_recommendations(improvement_plan)

    return {
        "plan": improvement_plan,
        "recommendations": recommendations,
        "implementation_priority": prioritize_improvements(recommendations)
    }

Usage Examples

Example 1: Validate Single File

python
# User wants to validate a specific file
Skill("moai-tag-policy-validator")

file_path = "src/main.py"
validation_result = validate_file_tags(file_path, read_file(file_path))

if validation_result.violations:
    display_violations(validation_result.violations)
    suggest_corrections(validation_result.violations)
else:
    display_success("All TAG policies compliant")

Example 2: Project-Wide Validation

python
# User wants to validate entire project
Skill("moai-tag-policy-validator")

violations = detect_policy_violations()
compliance_report = generate_compliance_report()

display_compliance_dashboard(compliance_report)

if violations["critical_violations"]:
    display_critical_alerts(violations["critical_violations"])

Example 3: TAG Chain Analysis

python
# User wants to analyze TAG chains
Skill("moai-tag-policy-validator")

chain_analysis = validate_tag_chains()

display_chain_analysis(chain_analysis)

if chain_analysis["broken_chains"]:
    display_chain_repair_suggestions(chain_analysis["broken_chains"])

End of Skill | Comprehensive TAG system validation and governance for maintaining TAG integrity and compliance

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results