Add cross-reference validation, upgrade CoC to Contributor Covenant v2.1

- Add CrossRefChecker with bidirectional and orphan detection (--check crossrefs)
- Upgrade Code of Conduct to Contributor Covenant v2.1
- Version bump v0.4.7

Closes #100
Closes #131

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Jeffallan

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Comprehensive skill pack for full-stack developers covering frameworks, workflows, and security",
-    "version": "0.4.6"
+    "version": "0.4.7"
   },
   "plugins": [
     {
       "name": "fullstack-dev-skills",
       "source": "./",
       "description": "66 specialized skills for full-stack development: 12 language experts (Python, TypeScript, Go, Rust, C++, Swift, Kotlin, C#, PHP, Java, SQL, JavaScript), 10 backend frameworks, 6 frontend/mobile, plus infrastructure, DevOps, security, and testing skills. Includes 9 project workflow commands for epic planning, discovery, execution, and retrospectives.",
-      "version": "0.4.6",
+      "version": "0.4.7",
       "author": {
         "name": "jeffallan",
         "email": "github@jeffallan"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstack-dev-skills",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Comprehensive skill pack with 66 specialized skills for full-stack developers: 12 language experts (Python, TypeScript, Go, Rust, C++, Swift, Kotlin, C#, PHP, Java, SQL, JavaScript), 10 backend frameworks, 6 frontend/mobile, plus infrastructure, DevOps, security, and testing. Features progressive disclosure architecture for 50% faster loading.",
   "author": {
         "name": "jeffallan",

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.7] - 2026-02-08
+
+### Added
+- Bidirectional cross-reference validation in `validate-skills.py` (closes #100)
+  - `CrossRefChecker` class: warns when skill A references B but B doesn't reference A
+  - Orphan detection: warns about skills with no incoming or outgoing references
+  - New `--check crossrefs` CLI option for isolated cross-reference validation
+  - All issues are WARNING severity (advisory, won't fail CI)
+
+### Changed
+- Upgraded Code of Conduct to Contributor Covenant v2.1 (closes #131)
+- Refactored `CrossRefChecker._build_graph()` to reuse `BaseChecker._extract_frontmatter()`
+
 ## [0.4.6] - 2026-02-08
 
 ### Added
@@ -320,6 +333,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Monitoring: Prometheus, Grafana, ELK, DataDog
 - Security: OWASP Top 10, SAST tools
 
+[0.4.7]: https://github.com/jeffallan/claude-skills/compare/v0.4.6...v0.4.7
 [0.4.6]: https://github.com/jeffallan/claude-skills/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/jeffallan/claude-skills/compare/v0.4.4...v0.4.5
 [0.4.4]: https://github.com/jeffallan/claude-skills/compare/v0.4.3...v0.4.4

CONTRIBUTING.md

@@ -287,20 +287,37 @@ Before submitting:
 
 ## Code of Conduct
 
-### Be Respectful
-- Be welcoming and inclusive
-- Respect differing viewpoints
-- Give and receive constructive feedback gracefully
-
-### Be Collaborative
-- Help others learn and grow
-- Share knowledge generously
-- Acknowledge contributions
-
-### Be Professional
-- Stay on topic
-- Assume good intent
-- Keep discussions productive
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+### Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+### Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+### Enforcement
+
+Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting the maintainers directly. All complaints will be reviewed and investigated promptly and fairly.
 
 ## Questions
 

README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/jeffallan/claude-skills"><img src="https://img.shields.io/badge/version-0.4.6-blue.svg?style=for-the-badge" alt="Version"/></a>
+  <a href="https://github.com/jeffallan/claude-skills"><img src="https://img.shields.io/badge/version-0.4.7-blue.svg?style=for-the-badge" alt="Version"/></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg?style=for-the-badge" alt="License"/></a>
   <a href="https://github.com/jeffallan/claude-skills"><img src="https://img.shields.io/badge/Claude_Code-Plugin-purple.svg?style=for-the-badge" alt="Claude Code"/></a>
   <a href="https://github.com/jeffallan/claude-skills/stargazers"><img src="https://img.shields.io/github/stars/jeffallan/claude-skills?style=for-the-badge&color=yellow" alt="Stars"/></a>

ROADMAP.md

@@ -2,7 +2,7 @@
 
 ## Current Status
 
-**Version:** v<!-- VERSION -->0.4.6<!-- /VERSION --> (Released January 2026)
+**Version:** v<!-- VERSION -->0.4.7<!-- /VERSION --> (Released January 2026)
 
 - **<!-- SKILL_COUNT -->66<!-- /SKILL_COUNT --> Skills** across 12 domains
 - **<!-- REFERENCE_COUNT -->365<!-- /REFERENCE_COUNT --> Reference Files** with progressive disclosure architecture
@@ -202,4 +202,4 @@ We welcome community input on the roadmap direction. Here's how you can contribu
 
 ---
 
-*This roadmap is a living document and subject to change based on community feedback, technical constraints, and emerging priorities. Last updated: February 2026 (v0.4.6)*
+*This roadmap is a living document and subject to change based on community feedback, technical constraints, and emerging priorities. Last updated: February 2026 (v0.4.7)*

assets/social-preview.png

@@ -10,6 +10,7 @@
     python scripts/validate-skills.py --check yaml # YAML-related checks only
     python scripts/validate-skills.py --check references  # Reference checks only
     python scripts/validate-skills.py --check workflows   # Workflow definition checks only
+    python scripts/validate-skills.py --check crossrefs   # Cross-reference validation only
     python scripts/validate-skills.py --skill react-expert  # Single skill
     python scripts/validate-skills.py --format json  # JSON for CI
 
@@ -287,34 +288,39 @@ class ValidationReport:
     results: list[ValidationResult] = field(default_factory=list)
     count_issues: list[ValidationIssue] = field(default_factory=list)
     workflow_issues: list[ValidationIssue] = field(default_factory=list)
+    crossref_issues: list[ValidationIssue] = field(default_factory=list)
 
     @property
     def has_errors(self) -> bool:
         return (
             any(r.has_errors for r in self.results)
             or any(i.severity == Severity.ERROR for i in self.count_issues)
             or any(i.severity == Severity.ERROR for i in self.workflow_issues)
+            or any(i.severity == Severity.ERROR for i in self.crossref_issues)
         )
 
     @property
     def total_errors(self) -> int:
         count = sum(1 for r in self.results for i in r.issues if i.severity == Severity.ERROR)
         count += sum(1 for i in self.count_issues if i.severity == Severity.ERROR)
         count += sum(1 for i in self.workflow_issues if i.severity == Severity.ERROR)
+        count += sum(1 for i in self.crossref_issues if i.severity == Severity.ERROR)
         return count
 
     @property
     def total_warnings(self) -> int:
         count = sum(1 for r in self.results for i in r.issues if i.severity == Severity.WARNING)
         count += sum(1 for i in self.count_issues if i.severity == Severity.WARNING)
         count += sum(1 for i in self.workflow_issues if i.severity == Severity.WARNING)
+        count += sum(1 for i in self.crossref_issues if i.severity == Severity.WARNING)
         return count
 
     def to_dict(self) -> dict:
         return {
             "results": [r.to_dict() for r in self.results],
             "count_issues": [i.to_dict() for i in self.count_issues],
             "workflow_issues": [i.to_dict() for i in self.workflow_issues],
+            "crossref_issues": [i.to_dict() for i in self.crossref_issues],
             "summary": {
                 "total_skills": len(self.results),
                 "total_errors": self.total_errors,
@@ -1533,6 +1539,97 @@ def check(self, skills_dir: Path) -> list[ValidationIssue]:
         return issues
 
 
+# =============================================================================
+# Cross-Reference Checker
+# =============================================================================
+
+class CrossRefChecker:
+    """Validates bidirectional related-skills references and detects orphan skills."""
+
+    name = "crossrefs"
+
+    def check(self, skills_dir: Path) -> list[ValidationIssue]:
+        issues = []
+        graph = self._build_graph(skills_dir)
+        issues.extend(self._check_bidirectional(graph))
+        issues.extend(self._check_orphans(graph, skills_dir))
+        return issues
+
+    def _build_graph(self, skills_dir: Path) -> dict[str, set[str]]:
+        """Parse all skills' metadata.related-skills into a graph."""
+        graph: dict[str, set[str]] = {}
+
+        for skill_path in sorted(skills_dir.iterdir()):
+            if not skill_path.is_dir() or skill_path.name.startswith("."):
+                continue
+
+            result = BaseChecker._extract_frontmatter(skill_path)
+            if result is None:
+                if (skill_path / "SKILL.md").exists():
+                    graph[skill_path.name] = set()
+                continue
+
+            metadata = result.frontmatter.get("metadata", {})
+            if not isinstance(metadata, dict):
+                graph[skill_path.name] = set()
+                continue
+
+            related = metadata.get("related-skills", "")
+            if isinstance(related, str) and related.strip():
+                refs = {r.strip() for r in related.split(",") if r.strip()}
+            else:
+                refs = set()
+
+            graph[skill_path.name] = refs
+
+        return graph
+
+    def _check_bidirectional(self, graph: dict[str, set[str]]) -> list[ValidationIssue]:
+        """Warn when A references B but B does not reference A."""
+        issues = []
+        reported: set[tuple[str, str]] = set()
+
+        for skill, refs in sorted(graph.items()):
+            for ref in sorted(refs):
+                if ref not in graph:
+                    continue  # Non-existent skill; MetadataFieldsChecker handles this
+                pair = (min(skill, ref), max(skill, ref))
+                if pair in reported:
+                    continue
+                if skill not in graph[ref]:
+                    reported.add(pair)
+                    issues.append(ValidationIssue(
+                        skill="__crossrefs__",
+                        check=self.name,
+                        severity=Severity.WARNING,
+                        message=f"'{skill}' references '{ref}' but '{ref}' does not reference '{skill}'",
+                    ))
+
+        return issues
+
+    def _check_orphans(
+        self, graph: dict[str, set[str]], skills_dir: Path
+    ) -> list[ValidationIssue]:
+        """Warn about skills with no incoming or outgoing references."""
+        issues = []
+
+        # Collect all skills that are referenced by at least one other skill
+        referenced: set[str] = set()
+        for refs in graph.values():
+            referenced.update(refs)
+
+        for skill, refs in sorted(graph.items()):
+            if not refs and skill not in referenced:
+                issues.append(ValidationIssue(
+                    skill="__crossrefs__",
+                    check=self.name,
+                    severity=Severity.WARNING,
+                    message=f"Orphan skill: '{skill}' has no related-skills and is not referenced by any other skill",
+                ))
+
+        return issues
+
+
 # =============================================================================
 # Workflow Validator
 # =============================================================================
@@ -1594,6 +1691,15 @@ def format(self, report: ValidationReport) -> str:
                 scope = f"[{issue.skill}] " if issue.skill else ""
                 lines.append(f"  [{icon}] {scope}{issue.check}: {issue.message}{file_info}")
 
+        # Cross-reference issues
+        if report.crossref_issues:
+            lines.append("")
+            lines.append("CROSS-REFERENCE ISSUES:")
+            lines.append("-" * 80)
+            for issue in report.crossref_issues:
+                icon = "ERROR" if issue.severity == Severity.ERROR else "WARN "
+                lines.append(f"  [{icon}] {issue.message}")
+
         # Count issues
         if report.count_issues:
             lines.append("")
@@ -1733,12 +1839,13 @@ def main():
   yaml        - YAML frontmatter validation (parsing, required fields, format)
   references  - Reference file validation (directory, count, headers)
   workflows   - Workflow YAML definitions, manifest DAG, orphan detection
+  crossrefs   - Bidirectional related-skills validation, orphan detection
 """,
     )
 
     parser.add_argument(
         "--check",
-        choices=["yaml", "references", "workflows"],
+        choices=["yaml", "references", "workflows", "crossrefs"],
         help="Run only checks in the specified category",
     )
 
@@ -1764,8 +1871,8 @@ def main():
 
     report = ValidationReport()
 
-    # Run skill validation (unless --check workflows)
-    if args.check != "workflows":
+    # Run skill validation (unless --check workflows or --check crossrefs)
+    if args.check not in ("workflows", "crossrefs"):
         validator = SkillValidator(
             skills_dir=args.skills_dir,
             check_category=args.check,
@@ -1779,6 +1886,11 @@ def main():
         workflow_validator = WorkflowValidator(base_path)
         report.workflow_issues = workflow_validator.validate()
 
+    # Run cross-reference validation (unless filtering to single skill or non-crossref category)
+    if args.check == "crossrefs" or (args.check is None and not args.skill):
+        crossref_checker = CrossRefChecker()
+        report.crossref_issues = crossref_checker.check(Path(args.skills_dir))
+
     # Format and output
     if args.format == "json":
         formatter = JsonFormatter()

scripts/validate-skills.py

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.6",
+  "version": "0.4.7",
   "skillCount": 66,
   "workflowCount": 9,
   "referenceFileCount": 365