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/decouple_agent_paths.py

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

Purpose:
    Rewrites hardcoded install-folder references (`.agents/skills/...`) in markdown
    instructions to the install-location-independent form required by the APM migration
    plan (docs/plans/apm_migration_plan.md, Section 6.2). Dry-run by default.

    Automatic rewrites (only where the result is unambiguous):
      R1  A skill's own script:    `.agents/skills/<self>/scripts/x.py` -> `scripts/x.py`
      R2  A skill's own file:      `.agents/skills/<self>/<path>`       -> `<path>`
      R3  Another skill's SKILL.md: `[t](.agents/skills/<n>/SKILL.md)`  -> `t (the `<n>` skill)`
                                    bare `.agents/skills/<n>/SKILL.md`  -> `the `<n>` skill`
    Everything else that mentions `.agents/` is reported for manual review with a reason
    (cross-skill script or file paths, folder-only mentions, Python code, ownership files).

Usage:
    python3 decouple_agent_paths.py --path <repo-root>              # dry-run report
    python3 decouple_agent_paths.py --path <repo-root> --apply      # write R1-R3 rewrites
    python3 decouple_agent_paths.py --path <repo-root> --json out.json

Exit codes: 0 success, 2 usage error.

Key Input Dependencies:
    - git (files are taken from `git ls-files` under --path)
    - Default exclusions: plugins/plugin-manager/ (decommissioned legacy installer),
      *ignore files, tests/, docs/plans/, .agent/rules/ (synced copies of plugin rules),
      history/ledger files (map-debt.md, evolution-log.md, CHANGELOG.md, backlog.md), research/

Function Index:
    - tracked_files(root) -> list[Path]
    - is_excluded(rel) -> bool
    - owning_skill(rel) -> str | None
    - rewrite_text(text, own_skill) -> tuple[str, list[dict]]
    - review_items(text, rel) -> list[dict]
    - scan(root, apply) -> dict
    - main() -> None
"""

import argparse
import json
import re
import subprocess
import sys
from pathlib import Path

EXCLUDED_PREFIXES = ("plugins/plugin-manager/", "docs/plans/", ".agent/rules/")
EXCLUDED_PARTS = ("/tests/", "/test/", "/research/", "/design-artifacts/")
# History and ledger files record what was true at the time; never rewrite them.
EXCLUDED_NAMES = ("map-debt.md", "evolution-log.md", "CHANGELOG.md", "backlog.md")
FENCE = re.compile(r"(```.*?```)", re.DOTALL)
INLINE_CODE = re.compile(r"(`[^`\n]+`)")
SKILL_REF = r"\.agents/skills/([\w-]+)/"
LINK_TO_SKILL = re.compile(r"\[([^\]]+)\]\(\.agents/skills/([\w-]+)/SKILL\.md\)")
BARE_SKILL_MD = re.compile(r"(?<![\w./-])\.agents/skills/([\w-]+)/SKILL\.md")
WHOLE_SPAN_SKILL_MD = re.compile(r"`\.agents/skills/([\w-]+)/SKILL\.md`")
OWN_PATH = r"\.agents/skills/{skill}/((?:[\w.-]+/)*[\w.-]+)"
ANY_AGENTS = re.compile(r"\.agents/[\w./-]*")


# List tracked files under the root (git keeps generated and ignored files out).
def tracked_files(root: Path) -> list[Path]:
    """Return tracked file paths relative to root."""
    out = subprocess.run(["git", "-C", str(root), "ls-files"], capture_output=True, text=True, check=True)
    return [Path(p) for p in out.stdout.splitlines()]


# Files that legitimately talk about the install folder, or are derived copies.
def is_excluded(rel: str) -> bool:
    """True for the legacy installer, ignore files, tests, plans and synced rule copies."""
    name = rel.rsplit("/", 1)[-1]
    if name.endswith("ignore") or name in EXCLUDED_NAMES or rel.startswith(EXCLUDED_PREFIXES):
        return True
    return any(part in "/" + rel for part in EXCLUDED_PARTS)


# The skill a file belongs to (plugins/<p>/skills/<skill>/...), if any.
def owning_skill(rel: str) -> str | None:
    """Return the skill folder name for a path inside plugins/*/skills/*/, else None."""
    parts = rel.split("/")
    if len(parts) > 4 and parts[0] == "plugins" and parts[2] == "skills":
        return parts[3]
    return None


# Apply R1-R3 to one markdown text; return the new text and the changes made.
# Only prose is rewritten: fenced code is skipped, and an inline code span is rewritten only
# when it is exactly a path (paths inside commands, JSON or tables of external repos stay).
def rewrite_text(text: str, own_skill: str | None) -> tuple[str, list[dict]]:
    """Rewrite unambiguous install-folder references; leave everything else untouched."""
    changes: list[dict] = []

    def record(rule: str, old: str, new: str) -> str:
        changes.append({"rule": rule, "old": old, "new": new})
        return new

    own = re.compile(OWN_PATH.format(skill=re.escape(own_skill))) if own_skill else None

    def own_sub(segment: str, whole_span: bool) -> str:
        def repl(m: re.Match) -> str:
            rule = "R1" if m.group(1).startswith("scripts/") else "R2"
            return record(rule, m.group(0), m.group(1))
        if not own:
            return segment
        if whole_span:
            inner = segment[1:-1]
            return f"`{own.sub(repl, inner)}`" if own.fullmatch(inner) else segment
        return own.sub(repl, segment)

    def prose(segment: str) -> str:
        parts = INLINE_CODE.split(segment)
        for i, part in enumerate(parts):
            if part.startswith("`") and part.endswith("`") and len(part) > 1:
                if WHOLE_SPAN_SKILL_MD.fullmatch(part):
                    name = WHOLE_SPAN_SKILL_MD.fullmatch(part).group(1)
                    parts[i] = record("R3", part, f"the `{name}` skill")
                else:
                    parts[i] = own_sub(part, whole_span=True)
                continue
            part = own_sub(part, whole_span=False)
            part = LINK_TO_SKILL.sub(lambda m: record("R3", m.group(0), f"{m.group(1)} (the `{m.group(2)}` skill)"), part)
            parts[i] = BARE_SKILL_MD.sub(lambda m: record("R3", m.group(0), f"the `{m.group(1)}` skill"), part)
        return "".join(parts)

    pieces = FENCE.split(text)
    return "".join(p if p.startswith("```") else prose(p) for p in pieces), changes


# Remaining `.agents/` mentions after rewriting, each with a review reason.
def review_items(text: str, rel: str) -> list[dict]:
    """Return manual-review items for install-folder mentions that were not rewritten."""
    items = []
    for line_no, line in enumerate(text.splitlines(), 1):
        for match in ANY_AGENTS.finditer(line):
            ref = match.group(0)
            if re.match(SKILL_REF + r"scripts/", ref):
                reason = "another skill's script: delegate to that skill by name (ADR-001) or share via the copy manifest"
            elif re.match(SKILL_REF, ref):
                reason = "another skill's file: markdown link within the plugin, or the skill by name"
            elif ref.startswith(".agents/ownership"):
                reason = "plugin-manager ownership manifest: replace with APM (--skill selections) in Phase 4"
            else:
                reason = "install-folder mention: describe by harness-neutral wording (plan Section 6.2)"
            items.append({"file": rel, "line": line_no, "ref": ref, "reason": reason})
    return items


# Walk tracked files, rewrite markdown (optionally writing), collect review items.
def scan(root: Path, apply: bool) -> dict:
    """Return {changed_files, changes, review} for the repository at root."""
    changed, review = [], []
    for rel_path in tracked_files(root):
        rel = rel_path.as_posix()
        path = root / rel_path
        if is_excluded(rel) or path.is_symlink() or not path.is_file():
            continue
        try:
            text = path.read_text(encoding="utf-8")
        except UnicodeDecodeError:
            continue
        if ".agents/" not in text:
            continue
        new_text, changes = (rewrite_text(text, owning_skill(rel)) if rel.endswith(".md") else (text, []))
        if changes:
            changed.append({"file": rel, "changes": changes})
            if apply:
                path.write_text(new_text, encoding="utf-8")
        review += review_items(new_text, rel)
    return {"applied": apply, "changed_files": changed, "review": review,
            "change_count": sum(len(c["changes"]) for c in changed)}


# CLI entry point.
def main() -> None:
    """Parse arguments, scan, print a summary and optionally write a JSON report."""
    parser = argparse.ArgumentParser(description="Decouple hardcoded .agents/ references (plan Section 6)")
    parser.add_argument("--path", default=".", help="Repository root (default: .)")
    parser.add_argument("--apply", action="store_true", help="Write R1-R3 rewrites (default: dry-run)")
    parser.add_argument("--json", help="Write the full report to this JSON file")
    args = parser.parse_args()
    result = scan(Path(args.path).resolve(), args.apply)
    mode = "APPLIED" if args.apply else "DRY-RUN"
    print(f"{mode}: {result['change_count']} rewrites in {len(result['changed_files'])} files; "
          f"{len(result['review'])} mentions need manual review")
    for item in result["changed_files"]:
        for change in item["changes"]:
            print(f"  [{change['rule']}] {item['file']}: {change['old']} -> {change['new']}")
    if args.json:
        Path(args.json).write_text(json.dumps(result, indent=2), encoding="utf-8")
        print(f"Report: {args.json}")
    sys.exit(0)


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