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

references/legacy-plugin-conversion-guide.md

View on GitHub
# Legacy Plugin to APM Migration Guide: The Interactive Master Playbook

Authoritative, interactive engineering playbook for converting legacy agent plugins (micro-skills, copy manifests, `symlinks.json`, `uvx plugin-add` stubs) into clean, self-contained, modal packages managed natively by Microsoft Agent Package Manager (APM).

This playbook encapsulates the full operational rigor of the 123-skill consolidation in `agent-plugins-skills` and the 108-skill consolidation in `sharepoint-knowledge-workbench`. It is designed to guide an agent through refactoring any downstream repository (e.g. SharePoint, Oracle Forms, bespoke enterprise systems) interactively, wave by wave.

---

## Contents

- [1. Core Philosophy: Why Staging Overlays Failed](#1-core-philosophy-why-staging-overlays-failed)
- [2. Phase 1: Interactive Discovery & Repository Intake](#2-phase-1-interactive-discovery--repository-intake)
- [3. Phase 2: Wave-by-Wave Mapping & Interactive Review](#3-phase-2-wave-by-wave-mapping--interactive-review)
- [4. Phase 3: The 8-Step Migration Lifecycle](#4-phase-3-the-8-step-migration-lifecycle)
- [5. Phase 4: Knowledge-Parity Assurance Matrix](#5-phase-4-knowledge-parity-assurance-matrix)
- [6. Phase 5: Deterministic Pre-Purge Accounting Check](#6-phase-5-deterministic-pre-purge-accounting-check)
- [7. Phase 6: Delegated Execution (Orchestrator and Worker Pattern)](#7-phase-6-delegated-execution-orchestrator-and-worker-pattern)
- [8. Phase 7: Scope Discipline & Git Hygiene](#8-phase-7-scope-discipline--git-hygiene)
- [9. Phase 8: Downstream Consumer Transition Cheat Sheet](#9-phase-8-downstream-consumer-transition-cheat-sheet)
- [10. Anti-Patterns & Common Pitfalls to Avoid](#10-anti-patterns--common-pitfalls-to-avoid)

---

## 1. Core Philosophy: Why Staging Overlays Failed

Early attempts to bridge legacy plugins to APM attempted to preserve hundreds of hyper-granular micro-skills by wrapping them in build-time staging pipelines (`scripts/apm_build_pipeline.py`) and copy manifests (`symlinks.json` with `strategy: "copy"`). While this eliminated broken symlinks on Windows, real-world deployment revealed fatal operational flaws:
1. **Maintainer Edit Hazard**: Maintainers frequently edited ephemeral copies inside `.claude/skills/` or `skills/<skill>/scripts/` instead of canonical source files, losing work upon re-materialization.
2. **Context Window Exhaustion**: Having 100+ granular micro-skills flooded the LLM's system prompt with tool definitions, drastically degrading routing precision and wasting tokens.
3. **Ghost Files on GitHub**: Materialized copies excluded via `.git/info/exclude` caused cloned repositories on GitHub to appear broken or missing critical scripts.

### The Modern Golden Path: Cohesive Modal Consolidation
Instead of wrapping fragmented micro-skills in fragile copy manifests, the authoritative standard is **Cohesive Modal Consolidation**:
- **Solution A (Modal Hub Consolidation)**: Collapse clusters of related micro-skills into a single, cohesive domain hub.
- **Solution B (1-to-1 Resource Co-location)**: Move scripts, assets, and tests directly into the owning skill as real, git-tracked physical files.
- **Zero Copy Manifests & Zero Symlinks**: Clean, self-contained spoke architecture that installs natively across all agent harnesses.

---

## 2. Phase 1: Interactive Discovery & Repository Intake

Every repository has its own history, design aspirations, runtime constraints, and hidden pitfalls. **Never begin restructuring files autonomously.** The agent must first conduct an interactive intake interview to uncover these nuances.

### The 5-Dimension Intake Questionnaire
Before writing code or manifests, present these structured questions to the operator:

1. **Target Repository & Baseline State**:
   - What is the absolute path, active branch, and Git status of the target repository?
   - Are there uncommitted changes or active worktrees that need resolution first?
2. **Current Footprint & Granularity**:
   - How many legacy plugins and micro-skills exist in `plugins/`?
   - What copy-manifest infrastructure is present (`symlinks.json`, `plugin-sources.json`, `skills-lock.json`, `.agents/`)?
3. **Design Aspirations & Target Architecture**:
   - Is the goal a single unified package (e.g. `@sharepoint/sharepoint-workbench`) or a small set of focused domain plugins?
   - What are the major domain hubs envisioned (e.g., Setup, Assessment, Conversion, Publishing, Migration)?
4. **Unique Repository Pitfalls & Caveats**:
   - Are there deep documentation or operational dependencies on existing skill names (e.g., Oracle Forms repositories where teams or scripts rely on legacy names)?
   - Are there runtime prerequisites (PowerShell 7+, PnP.PowerShell, Python virtual environments, Node.js)?
   - Are there Windows-specific symlink text stubs or platform-specific scripts?
5. **Downstream Consumers & Data Boundaries**:
   - Which external projects consume these skills (e.g. `jag-csb-intranet`)?
   - Which local paths represent customer data, secrets, or ledgers that must remain **strictly untouched** (e.g., `inventory/`, `config*.psd1`, `context/`)?

---

## 3. Phase 2: Wave-by-Wave Mapping & Interactive Review

Consolidating 50–100+ micro-skills all at once is high-risk and overwhelms human review. Partition the migration into **logical, staged waves** (typically 4 to 8 waves), and review them **one wave at a time**.

### The Canonical Mapping Plan Table
For each wave, author an explicit mapping proposal and present it to the operator before touching files:

```markdown
### Wave N Proposal: <Domain Name> (e.g., Site Build & Publishing)
**Legacy Scope**: `plugins/legacy-plugin` (33 micro-skills)
**Target Outcome**: 2 modal hub skills (`managing-sharepoint-schema`, `publishing-sharepoint-pages`)

| Legacy Micro-Skill | Target Consolidated Hub | Target Mode (`references/modes/`) | Absorbed Assets / Scripts | Special Invariants & Caveats |
|:---|:---|:---|:---|:---|
| `sp-site-columns` | `managing-sharepoint-schema` | `site-columns` | `scaffold_site_column.py` | Preserves field type mappings |
| `sp-content-types` | `managing-sharepoint-schema` | `content-types` | `scaffold_content_type.py` | Must run after site-columns |
| `sp-page-publish` | `publishing-sharepoint-pages` | `page-publication` | `publish_spo_page.ps1` | Requires `-ConfirmToken` gate |
| `sp-text-webpart` | `publishing-sharepoint-pages` | `rte-sanitization` | `sp_text_webpart_html.py` | Normalizes CKEditor tables |
```

### The Human Checkpoint
Prompt the operator:
> *"Does this Wave N mapping align with your operational workflow? Are there specific edge cases, prompt guards, or parameter options in these retiring skills that require special attention before we consolidate?"*

Incorporate human feedback, refine the mapping, and proceed to execution only after approval.

---

## 4. Phase 3: The 8-Step Migration Lifecycle

Once a wave mapping is approved, execute using the standardized 8-step lifecycle:

```
[1. Ledger CSV] ──► [2. Consolidate Hub] ──► [3. Co-locate Files] ──► [4. Evals & Schema]
                                                                              │
[8. Retire Old] ◄── [7. Consumer Matrix] ◄── [6. Pre-Purge Check] ◄── [5. Multi-Gates]
```

1. **Step 1: Inventory Ledger Initialization**:
   - Log every affected file into `master_migration_inventory.csv` (`Old Path, New Path, Action, Notes`).
2. **Step 2: Construct Modal Hub Spoke**:
   - Create `skills/<hub-skill>/SKILL.md` (< 100 lines) with metadata and mode dispatch table.
   - Author dedicated `references/modes/<mode>.md` files for each absorbed capability.
3. **Step 3: Self-Contained Resource Co-location**:
   - Move scripts and assets directly into `skills/<hub-skill>/scripts/` and `skills/<hub-skill>/references/`.
   - Never leave shared scripts at the plugin root. Real Git-tracked physical files only.
4. **Step 4: APM Manifest & Eval Schemas**:
   - Author `evals/evals.json` and `evals/task-success.json` as root JSON arrays (`[...]`).
   - Align subagent colors (`cyan`, `blue`, `purple`, `green`, `yellow`, `red`, `magenta`).
5. **Step 5: Deterministic Multi-Layer Verification**:
   - Run `audit_skill.py <path> --mode source`.
   - Run unit tests with `pytest`.
6. **Step 6: Pre-Purge Accounting Check**:
   - Run deterministic comparison script ensuring 100% of source files exist at target paths.
7. **Step 7: Downstream Consumer Refactor Matrix**:
   - Update consumer transition cheat sheet (1:1 matrix).
8. **Step 8: Retire Legacy Micro-Skills**:
   - Execute `git rm -rf` on retired folders only after Steps 1–7 pass.

---

## 5. Phase 4: Knowledge-Parity Assurance Matrix

Consolidation must **never drop knowledge, prompt guards, or review rules** established in retiring skills. Maintain an explicit checklist:

| Dimension | Verification Requirement |
| :--- | :--- |
| **Prompt Guards & Constraints** | All "DO NOT", "NEVER", and confirmation token requirements (`-ConfirmToken`) from legacy `SKILL.md` files must appear in the target mode file. |
| **Parameter Flags & CLI Syntax** | All CLI switches, environment variables, and config paths must be documented in `references/modes/<mode>.md`. |
| **Review Delimiters** | Structured review blocks (e.g. `PLAN REVIEW:`, `VERIFICATION:`) must be preserved verbatim. |
| **Error Recovery & Fallback** | Fallback trees and retry policies from legacy docs must be co-located under `references/`. |
| **Relative Markdown Links** | Subdocument links must be valid relative paths: `../<ref>.md` for sibling docs, `../../scripts/<script>` for scripts. |

---

## 6. Phase 5: Deterministic Pre-Purge Accounting Check

**Never delete legacy directories based on intuition.** Before deleting any legacy directory, execute an automated Python check verifying 100% file coverage:

```python
import csv
from pathlib import Path

def verify_accounting(csv_path: Path, repo_root: Path):
    with open(csv_path, "r", encoding="utf-8") as f:
        reader = csv.DictReader(f)
        for row in reader:
            if row["Action"] in ("MOVED_TO_SKILL", "CONSOLIDATED_INTO_SKILL"):
                target = repo_root / row["New Path"]
                if not target.exists():
                    raise FileNotFoundError(f"Missing target file: {target}")
    print("Pre-purge check PASSED: 100% of files accounted for.")
```

In the SharePoint Workbench refactor, this verified **760 out of 760 files** before running `git rm -rf`, guaranteeing zero data loss.

---

## 7. Phase 6: Delegated Execution (Orchestrator and Worker Pattern)

Large-scale refactorings across dozens of files should not be executed manually in tiny turns. Pair an **Orchestrator** with a high-throughput **Worker**:

```mermaid
sequenceDiagram
    autonumber
    actor Operator as Human Operator
    participant Orch as Orchestrator (Antigravity)
    participant Worker as Worker (Codex CLI / Luna 6)
    participant Harness as Verifier (audit_skill / pytest)

    Operator->>Orch: Review & Approve Wave Mapping
    Orch->>Worker: Dispatch In-Place Implementation Task
    Note over Worker: Direct workspace execution<br/>across all affected files
    Worker-->>Orch: Wave Implementation Complete
    Orch->>Harness: Run audit_skill.py & pytest
    alt Verifier Fails
        Orch->>Worker: Targeted Remediation with Error Traceback
    else Verifier Passes
        Orch->>Operator: Present Diff & Advance to Next Wave
    end
```

### Delegation Invariants
- **Direct Workspace Write Access**: Give the worker direct file-editing capabilities. Do **not** restrict it with `--isolated` or force code proposals to `/tmp`.
- **Zero Autonomous Commits by Worker**: The worker never runs `git commit` or `git push`. Git state hygiene is caller-managed by the Orchestrator.
- **Worker Preference**: For fast, deterministic multi-file edits, prefer **Codex CLI** (`codex exec` with Luna 6 / `gpt-5.6-luna` at medium reasoning effort).

---

## 8. Phase 7: Scope Discipline & Git Hygiene

Deploying APM packages requires strict scope discipline:

| Scope | Appropriate For | Why | Command |
| :--- | :--- | :--- | :--- |
| **Global Scope**<br>(`~/.apm/apm.yml`) | **Universal Developer Infrastructure** | Tools that apply to *every* repo (control plane, memory, orchestrator, authoring). | `apm install <abs-path> --global --target ...` |
| **Local Project Scope**<br>(`<repo>/apm.yml`) | **Domain-Specific Tooling** | Tools specific to one domain (SharePoint, Oracle Forms, specific APIs). | `apm install <pkg> --target ...` |

### Critical Scope Invariants
1. **Never Install Domain Packages Globally**: Installing domain skills globally bloats the system prompt in non-domain projects (e.g. general Python or React apps) and causes false-positive tool routing.
2. **Absolute Path for Local `--global`**: APM `0.33.0` rejects relative paths with `--global`. Use the full path:
   ```bash
   apm install /Users/.../plugins/my-plugin --global --target claude,copilot,codex,antigravity
   ```
3. **Consuming Project Git Hygiene**: Projects using local APM installs must exclude deployed harnesses in `.gitignore`:
   ```gitignore
   # APM Client Harnesses & Deployed Agents (ephemeral local copies)
   .agents/
   .claude/skills/
   .codex/
   .github/agents/
   apm_modules/
   ```
4. **Package Layout: Full APM-Native (`.apm/` Primitives)**:
   In the target package, primitives belong inside `.apm/` (`.apm/skills/`, `.apm/agents/`, `.apm/hooks/`, `.apm/prompts/`) with `type: full` declared in `apm.yml`. Never maintain duplicate root `skills/` or `agents/` directories alongside `.apm/`, and track `.apm/` in Git.


---

## 9. Phase 8: Downstream Consumer Transition Cheat Sheet

When consolidating micro-skills, downstream consumer projects (e.g. `jag-csb-intranet`) will break if they attempt to invoke retired skill names. Author a dedicated Consumer Refactoring Plan (e.g. `csb_intranet_sp_migration_refactor_plan.md`):

### Standard Transition Matrix Format
```markdown
## 1:1 Skill & Workflow Transition Matrix

| Legacy Micro-Skill | Consolidated Hub Skill | Target Mode / Command | What Changed / Notes |
|:---|:---|:---|:---|
| `sp-navigation-sync` | `managing-sharepoint-navigation` | `diff-navigation`<br>`sync-navigation` | Uses canonical `navigation_plan.py`. Requires `-ConfirmToken PROVISION-SPO-NAV`. |
| `sp-dynamic-aspx-page-migration` | `publishing-sharepoint-pages` | `dynamic-aspx-page-publication` | Same 7-stage workflow; outputs to modern canvas. |
| `sp-document-library-upload` | `managing-sharepoint-lists-and-libraries` | `library-upload-orchestration` | Powered by `library_migration_ledger.py`. |
```

Include exact before-and-after command snippets so automated scripts and developer workflows transition effortlessly.

---

## 10. Anti-Patterns & Common Pitfalls to Avoid

1. ❌ **Skipping the Intake Interview**: Starting to refactor without asking about the repo's unique documentation dependencies or customer data locations leads to breaking critical workflows.
2. ❌ **Bulk Autonomous Deletions**: Deleting legacy directories before verifying that 100% of source files exist at new paths risks irrecoverable file loss.
3. ❌ **Monolithic Conversions**: Attempting to convert 100+ skills in a single prompt turn. Always partition into 4–8 staged waves and review each wave interactively.
4. ❌ **Editing Deployed Copies**: Modifying files in `.agents/skills/` or `~/.claude/skills/` instead of source code under `plugins/`.
5. ❌ **Installing Domain Skills Globally**: Cluttering unrelated projects with domain-specific tools.
6. ❌ **Neglecting Consumer Mapping**: Failing to provide downstream repositories with a 1:1 transition matrix.
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