Sync CPV validators and bump version to 1.3.0

- Updated 13 validation scripts from upstream CPV
- Validation: 0 issues, 0 warnings, 947 passed

Author: Emasoft

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-maestro-orchestrator-agent",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "description": "Task distribution, agent coordination, progress monitoring - executes plans via subagents. Requires AI Maestro for inter-agent messaging.",
   "author": {
     "name": "Emasoft",

scripts/smart_exec.py

@@ -476,7 +476,12 @@ def choose_best(spec: ToolSpec, tool_args: list[str], executors: dict[str, bool]
 
 
 def parse_args(argv: list[str]) -> argparse.Namespace:
-    p = argparse.ArgumentParser(prog="smart_exec.py")
+    p = argparse.ArgumentParser(
+        prog="smart_exec.py",
+        description="Run developer tools using the best available executor (bun, uv, npm, pipx, docker, etc.).",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Examples:\n  uv run python scripts/smart_exec.py which ruff\n  uv run python scripts/smart_exec.py executors",
+    )
     sub = p.add_subparsers(dest="subcmd", required=True)
 
     p_run = sub.add_parser("run", help="Run a tool using the best available executor")

scripts/validate_agent.py

@@ -1128,7 +1128,11 @@ def print_json(report: AgentValidationReport) -> None:
 
 def main() -> int:
     """Main entry point."""
-    parser = argparse.ArgumentParser(description="Validate a Claude Code agent file or directory")
+    parser = argparse.ArgumentParser(
+        description="Validate a Claude Code agent file or directory of agents.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Example: uv run python scripts/validate_agent.py agents/",
+    )
     parser.add_argument("path", help="Path to agent .md file or agents/ directory")
     parser.add_argument(
         "--verbose",

scripts/validate_command.py

@@ -644,7 +644,11 @@ def print_json(report: CommandValidationReport) -> None:
 
 def main() -> int:
     """Main entry point."""
-    parser = argparse.ArgumentParser(description="Validate a Claude Code command file or directory")
+    parser = argparse.ArgumentParser(
+        description="Validate a Claude Code command file or directory of commands.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Example: uv run python scripts/validate_command.py commands/",
+    )
     parser.add_argument("path", help="Path to command .md file or commands/ directory")
     parser.add_argument(
         "--verbose",

scripts/validate_documentation.py

@@ -820,7 +820,11 @@ def main() -> int:
     Returns:
         Exit code (0=ok, 1=critical, 2=major, 3=minor)
     """
-    parser = argparse.ArgumentParser(description="Validate documentation files in a Claude Code plugin")
+    parser = argparse.ArgumentParser(
+        description="Validate documentation files in a Claude Code plugin.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Checks: README structure, broken links, code blocks, image refs, heading hierarchy.",
+    )
     parser.add_argument("plugin_path", help="Path to the plugin directory")
     parser.add_argument(
         "--verbose",

scripts/validate_hook.py

@@ -1014,7 +1014,11 @@ def print_json(report: HookValidationReport) -> None:
 
 def main() -> int:
     """Main entry point."""
-    parser = argparse.ArgumentParser(description="Validate a Claude Code hooks.json file")
+    parser = argparse.ArgumentParser(
+        description="Validate a Claude Code hooks.json file.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Example: uv run python scripts/validate_hook.py hooks/hooks.json --plugin-root .",
+    )
     parser.add_argument("hook_path", help="Path to the hooks.json file")
     parser.add_argument(
         "--plugin-root",

scripts/validate_lsp.py

@@ -463,7 +463,10 @@ def print_results(report: ValidationReport, verbose: bool = False) -> None:
 
 def main() -> int:
     """Main entry point."""
-    parser = argparse.ArgumentParser(description="Validate LSP configuration")
+    parser = argparse.ArgumentParser(
+        description="Validate LSP (Language Server Protocol) server configuration for Claude Code plugins.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
     parser.add_argument("--verbose", "-v", action="store_true", help="Show all results")
     parser.add_argument("--json", action="store_true", help="Output as JSON")
     parser.add_argument("--strict", action="store_true", help="Strict mode — NIT issues also block validation")

scripts/validate_marketplace_pipeline.py

@@ -1461,6 +1461,8 @@ def main() -> int:
         description="Validate marketplace publishing pipeline automation",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
+Checks: GitHub Actions workflows, CI scripts, validation pipeline, deployment config.
+
 Examples:
   %(prog)s /path/to/marketplace
   %(prog)s /path/to/marketplace --verbose

scripts/validate_mcp.py

@@ -534,7 +534,10 @@ def print_results(report: ValidationReport, verbose: bool = False) -> None:
 
 def main() -> int:
     """Main entry point."""
-    parser = argparse.ArgumentParser(description="Validate MCP configuration")
+    parser = argparse.ArgumentParser(
+        description="Validate MCP (Model Context Protocol) server configuration for Claude Code plugins.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
     parser.add_argument("--verbose", "-v", action="store_true", help="Show all results")
     parser.add_argument("--strict", action="store_true", help="Strict mode — NIT issues also block validation")
     parser.add_argument("--json", action="store_true", help="Output as JSON")

scripts/validate_plugin.py

@@ -1335,7 +1335,11 @@ def print_json(report: ValidationReport) -> None:
 
 def main() -> int:
     """Main entry point."""
-    parser = argparse.ArgumentParser(description="Validate Claude Code plugin")
+    parser = argparse.ArgumentParser(
+        description="Validate a Claude Code plugin against all validation rules.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="This is the main entry point. It orchestrates all 17 sub-validators.\nExample: uv run python scripts/validate_plugin.py . --strict --verbose",
+    )
     parser.add_argument(
         "--verbose",
         "-v",