Skip to content

richfrem/agent-plugins-skills / plugins/agent-extension-authoring/.apm/skills/packaging-with-apm

packaging-with-apm

Flagged

Packages, installs and distributes agent extensions with APM (Agent Package Manager). Use when the user wants to create a new APM package, convert or migrate an existing plugin to APM and check it installs cleanly, compile a package into AGENTS.md, CLAUDE.md or GEMINI.md, install, update, pin or roll back packages globally or per project, or create a plugin marketplace catalog (marketplace.json). Not for authoring a single skill, plugin, sub-agent or rule (use the authoring-* skills).

FileKindSize
SKILL.mdskill md5.3 KB
evals/evals.jsonconfig2.7 KB
examples/marketplace.jsonconfig45 B
references/acceptance-criteria.mdmarkdown4.6 KB
references/agent-package-manager-overview.mdmarkdown28.7 KB
references/apm-alignment-fixes.mdmarkdown5.3 KB
references/diagrams/packaging-with-apm-flow.mmdother590 B
references/fallback-tree.mdmarkdown1.8 KB
references/legacy-plugin-conversion-guide.mdmarkdown15.4 KB
references/marketplace-architecture.mdmarkdown1.5 KB
references/marketplace-schema.mdmarkdown2.5 KB
references/marketplace.mdmarkdown11.5 KB
references/modes/compile-apm-package.mdmarkdown1.7 KB
references/modes/convert-plugin-to-apm.mdmarkdown7.3 KB
references/modes/create-apm-package.mdmarkdown1.7 KB
references/modes/install-apm-package.mdmarkdown4.3 KB
references/modes/manage-marketplace.mdmarkdown2.1 KB
requirements-dev.inother657 B
requirements-dev.txtmarkdown3.3 KB
requirements.inother148 B
requirements.txtmanifest171 B
scripts/apm_build_pipeline.pyscript35.1 KB
scripts/apm_consumer.pyscript11.3 KB
scripts/apply_symlink_repairs.pyscript1.7 KB
scripts/apply_symlink_repairs.shscript40 B
scripts/audit_marketplace_sources.pyscript2.5 KB
scripts/check_for_broken_symlinks.pyexecutablescript6.6 KB
scripts/convert_symlinks_to_manifest.pyscript6.7 KB
scripts/decouple_agent_paths.pyscript9.1 KB
scripts/fix_inside_plugin_symlinks.pyscript11.3 KB
scripts/materialize_copies.pyscript5.3 KB
scripts/migrate_to_apm.pyscript16.4 KB
scripts/scaffold_apm.pyscript8.6 KB
scripts/validate_apm_package.pyscript5.7 KB
tests/test_apm_build_pipeline.pyscript10.2 KB
tests/test_apm_consumer.pyscript4.8 KB
tests/test_audit_decoupled_state.pyscript8.6 KB
tests/test_convert_symlinks_to_manifest.pyscript5.3 KB
tests/test_decouple_agent_paths.pyscript4.8 KB
tests/test_scaffold_apm.pyscript1.7 KB

scripts/validate_apm_package.py

View on GitHub
#!/usr/bin/env python
"""
validate_apm_package.py (CLI)
=====================================

Purpose:
    Performs deterministic validation of an APM package.

Key Input Dependencies:
    - PyYAML                    — Used for parsing apm.yml package manifests and policy configurations
    - argparse, json, re, sys   — Standard library packages for CLI parsing, reporting, and name matching
"""

import argparse
import os
import yaml
import sys
import json
import re
from pathlib import Path

# Windows encoding safety
if sys.platform == "win32":
    try:
        sys.stdout.reconfigure(encoding='utf-8', errors='replace')
        sys.stderr.reconfigure(encoding='utf-8', errors='replace')
    except (AttributeError, Exception): pass

def _check_manifest(root: Path, issues: list, warnings: list) -> dict:
    """Parse and validate apm.yml; return the manifest dict."""
    manifest: dict = {}
    manifest_path = root / "apm.yml"
    if not manifest_path.exists():
        issues.append("MISSING: apm.yml is required.")
        return manifest
    try:
        with open(manifest_path, "r", encoding="utf-8") as f:
            manifest = yaml.safe_load(f) or {}
        name = manifest.get("name", "")
        version = manifest.get("version", "")
        if name and not re.match(r'^[a-z0-9-]+$', name):
            issues.append(f"SCHEMA: Name '{name}' must be kebab-case.")
        if version and not re.match(r'^\d+\.\d+\.\d+', str(version)):
            warnings.append(f"SCHEMA: Version '{version}' should follow semver (x.y.z).")
        if not name:
            issues.append("SCHEMA: 'name' is required.")
        if not version:
            issues.append("SCHEMA: 'version' is required.")
    except Exception as e:
        issues.append(f"PARSE: {e}")
    return manifest


def _check_structure(root: Path, manifest: dict, issues: list, warnings: list) -> bool:
    """Check .apm/ structure and primitive directories; return has_apm."""
    metadata = manifest.get("metadata", {})
    mode = metadata.get("packaging_mode", "unknown")
    has_apm = (root / ".apm").exists()
    if mode == "full":
        if not has_apm:
            issues.append("STRUCTURE: Full mode requires .apm/ directory.")
        for folder in ["skills", "agents", "prompts", "hooks"]:
            if (root / folder).exists() and (root / ".apm" / folder).exists():
                issues.append(f"STRUCTURE: Duplicate primitive root '{folder}/' found outside .apm/ in Full mode.")
    elif mode == "hybrid":
        if not has_apm:
            warnings.append("STRUCTURE: Hybrid mode normally includes a .apm/ directory.")
    if has_apm:
        hooks_dir = root / ".apm" / "hooks"
        if hooks_dir.exists() and not list(hooks_dir.glob("*.json")):
            warnings.append("PRIMITIVES: .apm/hooks/ exists but contains no .json files.")
        prompts_dir = root / ".apm" / "prompts"
        if prompts_dir.exists():
            generic_md = [f.name for f in prompts_dir.glob("*.md") if not f.name.endswith(".prompt.md")]
            if generic_md:
                warnings.append(f"PRIMITIVES: .apm/prompts/ contains generic .md files: {generic_md}.")
    return has_apm


def _check_governance(root: Path, manifest: dict, issues: list, warnings: list) -> None:
    """Check enterprise governance policy and README presence."""
    metadata = manifest.get("metadata", {})
    lane = metadata.get("governance_lane", "unknown")
    if lane == "enterprise":
        policy_path = root / "apm-policy.yml"
        if not policy_path.exists():
            warnings.append("GOVERNANCE: Enterprise lane recommends an apm-policy.yml.")
        else:
            with open(policy_path, "r", encoding="utf-8") as f:
                policy_content = f.read()
            if "company.com" in policy_content or "my-org" in policy_content:
                warnings.append("GOVERNANCE: apm-policy.yml appears to contain template placeholders.")
    if not (root / "README.md").exists():
        warnings.append("DOCS: Missing README.md.")


def _print_result(result: dict) -> None:
    """Print human-readable validation result to stdout."""
    root_name = Path(result["path"]).name
    print(f"\U0001f50d Auditing: {root_name}\n" + "-" * 40)
    for i in result["issues"]:
        print(f"\u274c {i}")
    for w in result["warnings"]:
        print(f"\u26a0\ufe0f  {w}")
    print("-" * 40)
    print("\u2705 VALIDATION PASSED" if result["passed"] else "\u274c VALIDATION FAILED")


def validate_package(path: str, as_json: bool = False) -> bool:
    """Deterministic validation of an APM package's directories, manifest, and governance policy."""
    root = Path(path).resolve()
    if not root.exists():
        if not as_json:
            print(f"\u274c Error: Path '{root}' does not exist.")
        return False
    issues: list = []
    warnings: list = []
    manifest = _check_manifest(root, issues, warnings)
    _check_structure(root, manifest, issues, warnings)
    _check_governance(root, manifest, issues, warnings)
    metadata = manifest.get("metadata", {})
    result = {
        "path": str(root), "passed": len(issues) == 0,
        "issues": issues, "warnings": warnings,
        "mode": metadata.get("packaging_mode", "unknown"),
        "governance_lane": metadata.get("governance_lane", "unknown"),
    }
    if as_json:
        print(json.dumps(result, indent=2))
    else:
        _print_result(result)
    return result["passed"]

def main():
    """CLI entry point: parses CLI arguments and runs the APM package validation."""
    parser = argparse.ArgumentParser(description="APM Package Validator")
    parser.add_argument("--path", required=True)
    parser.add_argument("--json", action="store_true")
    args = parser.parse_args()
    sys.exit(0 if validate_package(args.path, args.json) else 1)

if __name__ == "__main__": main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall