feat(factory): add native Droid plugin packaging (#120)

* feat(factory): add native Droid plugin packaging

* test(factory): guard documented install contract

* fix(factory): enforce install command order

scripts/bump-plugin-version.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Increment the synchronized Claude and Codex plugin manifest versions."""
+"""Increment the synchronized Claude, Codex, and Factory manifest versions."""
 
 from __future__ import annotations
 
@@ -14,6 +14,7 @@ ROOT = Path(__file__).resolve().parent.parent
 MANIFEST_PATHS = (
     Path(".claude-plugin/plugin.json"),
     Path(".codex-plugin/plugin.json"),
+    Path(".factory-plugin/plugin.json"),
 )
 SEMVER = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
 
@@ -46,7 +47,7 @@ def bump(root: Path, part: str = "patch") -> str:
     if any(version != raw_versions[0] for version in raw_versions[1:]):
         rendered = ", ".join(
             f"{relative}={version!r}"
-            for (relative, _), version in zip(manifests, raw_versions, strict=True)
+            for (relative, _), version in zip(manifests, raw_versions)
         )
         raise PackageVersionError(f"manifest versions are not synchronized: {rendered}")
 
@@ -74,7 +75,7 @@ def bump(root: Path, part: str = "patch") -> str:
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
-        description="Increment both plugin manifests (patch by default)."
+        description="Increment all plugin manifests (patch by default)."
     )
     group = parser.add_mutually_exclusive_group()
     group.add_argument("--major", action="store_true", help="increment the major version")
@@ -90,7 +91,7 @@ def main() -> int:
     except PackageVersionError as exc:
         print(f"ERROR: {exc}", file=sys.stderr)
         return 1
-    print(f"Updated Claude and Codex plugin manifests to {version}")
+    print(f"Updated Claude, Codex, and Factory plugin manifests to {version}")
     return 0
 
 

scripts/test-plugin-package.py

@@ -11,7 +11,7 @@ import tempfile
 from contextlib import contextmanager
 from pathlib import Path
 from types import ModuleType
-from typing import Iterator
+from typing import Iterator, Optional
 
 ROOT = Path(__file__).resolve().parent.parent
 VERIFY_SCRIPT = ROOT / "scripts/verify-plugin-package.py"
@@ -50,9 +50,24 @@ def manifest(version: str, codex: bool = False) -> dict:
     return payload
 
 
-def seed_package(root: Path, version: str = "1.2.3") -> None:
+def seed_factory(root: Path, version: str) -> None:
+    write_json(root / ".factory-plugin/plugin.json", manifest(version))
+    write_json(
+        root / ".factory-plugin/marketplace.json",
+        {
+            "name": PLUGIN_NAME,
+            "plugins": [{"name": PLUGIN_NAME, "source": "./"}],
+        },
+    )
+
+
+def seed_package(
+    root: Path, version: str = "1.2.3", include_factory: bool = True
+) -> None:
     write_json(root / ".claude-plugin/plugin.json", manifest(version))
     write_json(root / ".codex-plugin/plugin.json", manifest(version, codex=True))
+    if include_factory:
+        seed_factory(root, version)
     write_json(
         root / ".claude-plugin/marketplace.json",
         {
@@ -80,13 +95,16 @@ def seed_package(root: Path, version: str = "1.2.3") -> None:
     skill = root / "skills" / PLUGIN_NAME / "SKILL.md"
     skill.parent.mkdir(parents=True, exist_ok=True)
     skill.write_text(f"---\nname: {PLUGIN_NAME}\n---\n", encoding="utf-8")
+    command = root / "commands" / "export-diagram.md"
+    command.parent.mkdir(parents=True, exist_ok=True)
+    command.write_text("Export the diagram.\n", encoding="utf-8")
 
 
 @contextmanager
-def package_repo() -> Iterator[Path]:
+def package_repo(include_factory: bool = True) -> Iterator[Path]:
     with tempfile.TemporaryDirectory() as scratch:
         root = Path(scratch)
-        seed_package(root)
+        seed_package(root, include_factory=include_factory)
         subprocess.run(["git", "init", "-q"], cwd=root, check=True)
         subprocess.run(["git", "config", "user.name", "Package Test"], cwd=root, check=True)
         subprocess.run(
@@ -99,16 +117,31 @@ def package_repo() -> Iterator[Path]:
         yield root
 
 
-def set_versions(root: Path, claude: str, codex: str) -> None:
+def set_versions(
+    root: Path, claude: str, codex: str, factory: Optional[str] = None
+) -> None:
+    if factory is None:
+        factory = codex
     for relative, version in (
         (Path(".claude-plugin/plugin.json"), claude),
         (Path(".codex-plugin/plugin.json"), codex),
+        (Path(".factory-plugin/plugin.json"), factory),
     ):
         payload = json.loads((root / relative).read_text(encoding="utf-8"))
         payload["version"] = version
         write_json(root / relative, payload)
 
 
+def set_existing_versions(root: Path, version: str) -> None:
+    for relative in VERIFY.MANIFEST_PATHS.values():
+        path = root / relative
+        if not path.is_file():
+            continue
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        payload["version"] = version
+        write_json(path, payload)
+
+
 def expect_failure(label: str, errors: list[str], needle: str) -> None:
     if not any(needle in error for error in errors):
         raise AssertionError(f"{label}: expected {needle!r}, got {errors}")
@@ -138,6 +171,14 @@ def test_verifier() -> None:
             "versions must match",
         )
 
+    with package_repo() as root:
+        set_versions(root, "1.2.4", "1.2.4", "1.2.5")
+        expect_failure(
+            "Factory version drift",
+            VERIFY.verify_package(root, "HEAD"),
+            "versions must match",
+        )
+
     with package_repo() as root:
         set_versions(root, "1.2", "1.2")
         expect_failure(
@@ -158,6 +199,68 @@ def test_verifier() -> None:
             "target does not exist",
         )
 
+    with package_repo() as root:
+        set_versions(root, "1.2.4", "1.2.4")
+        marketplace_path = root / ".factory-plugin/marketplace.json"
+        marketplace = json.loads(marketplace_path.read_text(encoding="utf-8"))
+        marketplace["plugins"][0]["source"] = {
+            "source": "local",
+            "path": "./",
+        }
+        write_json(marketplace_path, marketplace)
+        expect_failure(
+            "non-native Factory marketplace source",
+            VERIFY.verify_package(root, "HEAD"),
+            "must be a non-empty local path string",
+        )
+
+    with package_repo() as root:
+        set_versions(root, "1.2.4", "1.2.4")
+        (root / "commands/export-diagram.md").unlink()
+        expect_failure(
+            "missing shared command surface",
+            VERIFY.verify_package(root, "HEAD"),
+            "packaged commands are missing",
+        )
+
+    with package_repo(include_factory=False) as root:
+        set_existing_versions(root, "1.2.4")
+        seed_factory(root, "1.2.4")
+        errors = VERIFY.verify_package(root, "HEAD")
+        if errors:
+            raise AssertionError(f"valid Factory bootstrap failed: {errors}")
+        print("OK: synchronized Factory bootstrap accepted")
+
+    with package_repo(include_factory=False) as root:
+        seed_factory(root, "1.2.3")
+        expect_failure(
+            "Factory bootstrap without package bump",
+            VERIFY.verify_package(root, "HEAD"),
+            "must increase",
+        )
+
+    with package_repo(include_factory=False) as root:
+        set_existing_versions(root, "1.2.4")
+        seed_factory(root, "1.2.4")
+        factory_path = root / ".factory-plugin/plugin.json"
+        factory = json.loads(factory_path.read_text(encoding="utf-8"))
+        factory["description"] = "Drifted Factory description."
+        write_json(factory_path, factory)
+        expect_failure(
+            "Factory bootstrap with manifest drift",
+            VERIFY.verify_package(root, "HEAD"),
+            "must match Claude",
+        )
+
+    with package_repo() as root:
+        set_versions(root, "1.2.4", "1.2.4")
+        (root / ".factory-plugin/plugin.json").unlink()
+        expect_failure(
+            "Factory manifest deletion",
+            VERIFY.verify_package(root, "HEAD"),
+            "could not read",
+        )
+
 
 def test_bumper() -> None:
     cases = (("patch", "1.2.4"), ("minor", "1.3.0"), ("major", "2.0.0"))

scripts/test-verify-docs-sync.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import importlib.util
+import json
 import sys
 import tempfile
 from pathlib import Path
@@ -90,8 +91,97 @@ def main() -> int:
         if errors != [expected]:
             raise AssertionError(f"stale Pi prompt was not reported: {errors}")
 
+        factory_manifest = root / ".factory-plugin/plugin.json"
+        factory_marketplace = root / ".factory-plugin/marketplace.json"
+        factory_manifest.parent.mkdir(parents=True)
+        factory_manifest.write_text(
+            json.dumps(
+                {
+                    "name": "diagram-design",
+                    "repository": "https://github.com/example/diagram-design",
+                }
+            ),
+            encoding="utf-8",
+        )
+        factory_marketplace.write_text(
+            json.dumps({"name": "diagram-design"}),
+            encoding="utf-8",
+        )
+        valid_readme = """# Diagram Design
+
+```bash
+droid plugin marketplace add https://github.com/example/diagram-design
+droid plugin install diagram-design@diagram-design --scope user
+```
+
+```
+diagram-design/
+├── .factory-plugin/ — Factory Droid metadata
+├── commands/
+└── skills/
+```
+"""
+        readme = root / "README.md"
+        readme.write_text(valid_readme, encoding="utf-8")
+
+        errors = []
+        verify.check_factory_install_surface(errors, root)
+        if errors:
+            raise AssertionError(f"valid Factory install contract failed: {errors}")
+
+        readme.write_text(
+            valid_readme.replace(
+                "droid plugin marketplace add https://github.com/example/diagram-design\n"
+                "droid plugin install diagram-design@diagram-design --scope user",
+                "droid plugin install diagram-design@diagram-design --scope user\n"
+                "droid plugin marketplace add https://github.com/example/diagram-design",
+            ),
+            encoding="utf-8",
+        )
+        errors = []
+        verify.check_factory_install_surface(errors, root)
+        expected = (
+            "README Factory install block must match native metadata: "
+            "`droid plugin marketplace add https://github.com/example/diagram-design` "
+            "then `droid plugin install diagram-design@diagram-design`"
+        )
+        if errors != [expected]:
+            raise AssertionError(
+                f"reversed Factory install commands were not reported: {errors}"
+            )
+
+        readme.write_text(
+            valid_readme.replace(
+                "diagram-design@diagram-design", "diagram-design@wrong-marketplace"
+            ),
+            encoding="utf-8",
+        )
+        errors = []
+        verify.check_factory_install_surface(errors, root)
+        expected = (
+            "README Factory install block must match native metadata: "
+            "`droid plugin marketplace add https://github.com/example/diagram-design` "
+            "then `droid plugin install diagram-design@diagram-design`"
+        )
+        if errors != [expected]:
+            raise AssertionError(
+                f"drifted Factory plugin ID was not reported: {errors}"
+            )
+
+        readme.write_text(
+            valid_readme.replace("├── .factory-plugin/ — Factory Droid metadata\n", ""),
+            encoding="utf-8",
+        )
+        errors = []
+        verify.check_factory_install_surface(errors, root)
+        expected = (
+            "README architecture tree must list Factory's native .factory-plugin/ path"
+        )
+        if errors != [expected]:
+            raise AssertionError(f"missing Factory native path was not reported: {errors}")
+
     print(
-        "PASS: docs sync checks reference links and Claude/Pi profile-surface parity"
+        "PASS: docs sync checks references, profile surfaces, and Factory install contract"
     )
     return 0
 

scripts/verify-docs-sync.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Verify that routing and browsing surfaces stay in sync with the skill.
 
-Five drift classes, each of which has shipped before:
+Seven drift classes, each of which has shipped before:
 
 1. The SKILL.md frontmatter description is the only text an agent sees before
    deciding to load the skill — every visual type in the selection table must
@@ -15,6 +15,8 @@ Five drift classes, each of which has shipped before:
    text a user reads *before installing*, so by ADR 0004's own argument they
    need every type's lexical hook too - and nothing else notices when they
    drift, because they are four separate copies of one sentence.
+7. Factory Droid's README install commands and native manifest path must agree
+   with the package metadata instead of becoming a second hand-maintained API.
 """
 
 from __future__ import annotations
@@ -40,6 +42,8 @@ PROFILE_SURFACES = (
     Path("commands/profile.md"),
     Path("prompts/profile.md"),
 )
+FACTORY_MANIFEST = Path(".factory-plugin/plugin.json")
+FACTORY_MARKETPLACE = Path(".factory-plugin/marketplace.json")
 
 
 def normalized(text: str) -> str:
@@ -156,10 +160,56 @@ def check_profile_surfaces(errors: list[str], root: Path) -> None:
             )
 
 
+def check_factory_install_surface(errors: list[str], root: Path) -> None:
+    markdown = (root / "README.md").read_text(encoding="utf-8")
+    manifest = json.loads((root / FACTORY_MANIFEST).read_text(encoding="utf-8"))
+    marketplace = json.loads((root / FACTORY_MARKETPLACE).read_text(encoding="utf-8"))
+    code_blocks = re.findall(
+        r"^```[^\n]*\n(.*?)^```[ \t]*$", markdown, re.MULTILINE | re.DOTALL
+    )
+
+    marketplace_command = f"droid plugin marketplace add {manifest['repository']}"
+    install_command = f"droid plugin install {manifest['name']}@{marketplace['name']}"
+    command_blocks = [
+        [line.strip() for line in block.splitlines() if line.strip()]
+        for block in code_blocks
+    ]
+    install_is_documented = any(
+        any(
+            line == install_command or line.startswith(f"{install_command} ")
+            for line in lines[lines.index(marketplace_command) + 1 :]
+        )
+        for lines in command_blocks
+        if marketplace_command in lines
+    )
+    if not install_is_documented:
+        errors.append(
+            "README Factory install block must match native metadata: "
+            f"`{marketplace_command}` then `{install_command}`"
+        )
+
+    native_directory = f"{FACTORY_MANIFEST.parent.as_posix()}/"
+    architecture_blocks = [
+        block
+        for block in code_blocks
+        if "diagram-design/" in block and "commands/" in block
+    ]
+    native_path_is_documented = any(
+        line.lstrip(" │├─└").startswith(native_directory)
+        for block in architecture_blocks
+        for line in block.splitlines()
+    )
+    if not native_path_is_documented:
+        errors.append(
+            f"README architecture tree must list Factory's native {native_directory} path"
+        )
+
+
 MANIFEST_DESCRIPTIONS = (
     (Path(".claude-plugin/plugin.json"), ("description",)),
     (Path(".claude-plugin/marketplace.json"), ("description",)),
     (Path(".codex-plugin/plugin.json"), ("description", "longDescription")),
+    (FACTORY_MANIFEST, ("description",)),
 )
 
 
@@ -212,6 +262,7 @@ def main() -> int:
     errors: list[str] = []
     check_description(errors)
     check_manifest_descriptions(errors, ROOT)
+    check_factory_install_surface(errors, ROOT)
     check_gallery(errors)
     check_readme_tree(errors)
     check_skill_reference_links(
@@ -227,7 +278,7 @@ def main() -> int:
         return 1
     print(
         "OK docs sync: description hooks, gallery reachability, README tree, "
-        "reference links, profile surfaces, manifest descriptions"
+        "reference links, profile surfaces, manifest descriptions, Factory install contract"
     )
     return 0
 

scripts/verify-plugin-package.py

@@ -15,9 +15,21 @@ PLUGIN_NAME = "diagram-design"
 MANIFEST_PATHS = {
     "Claude": Path(".claude-plugin/plugin.json"),
     "Codex": Path(".codex-plugin/plugin.json"),
+    "Factory": Path(".factory-plugin/plugin.json"),
 }
 CLAUDE_MARKETPLACE = Path(".claude-plugin/marketplace.json")
 CODEX_MARKETPLACE = Path(".agents/plugins/marketplace.json")
+FACTORY_MARKETPLACE = Path(".factory-plugin/marketplace.json")
+SHARED_MANIFEST_FIELDS = (
+    "name",
+    "description",
+    "version",
+    "author",
+    "homepage",
+    "repository",
+    "license",
+    "keywords",
+)
 SEMVER = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
 
 
@@ -36,7 +48,20 @@ def load_json(path: Path, errors: list[str]) -> dict[str, Any] | None:
     return payload
 
 
-def load_base_json(root: Path, base_ref: str, relative: Path, errors: list[str]) -> dict[str, Any] | None:
+def base_path_exists(root: Path, base_ref: str, relative: Path) -> bool:
+    result = subprocess.run(
+        ["git", "cat-file", "-e", f"{base_ref}:{relative.as_posix()}"],
+        cwd=root,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def load_base_json(
+    root: Path, base_ref: str, relative: Path, errors: list[str]
+) -> dict[str, Any] | None:
     result = subprocess.run(
         ["git", "show", f"{base_ref}:{relative.as_posix()}"],
         cwd=root,
@@ -125,10 +150,26 @@ def verify_versions(
     version_values = list(current_versions.values())
     if any(version != version_values[0] for version in version_values[1:]):
         rendered = ", ".join(f"{label}={value!r}" for label, value in current_versions.items())
-        errors.append(f"Claude and Codex manifest versions must match: {rendered}")
+        errors.append(f"plugin manifest versions must match: {rendered}")
 
+    base_check = subprocess.run(
+        ["git", "rev-parse", "--verify", f"{base_ref}^{{commit}}"],
+        cwd=root,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if base_check.returncode != 0:
+        detail = base_check.stderr.strip() or "not a commit"
+        errors.append(f"could not resolve base ref {base_ref!r}: {detail}")
+        return
+
+    base_manifest_count = 0
     for label, relative in MANIFEST_PATHS.items():
         current = parse_semver(current_versions.get(label), f"current {label}", errors)
+        if not base_path_exists(root, base_ref, relative):
+            continue
+        base_manifest_count += 1
         base_manifest = load_base_json(root, base_ref, relative, errors)
         if base_manifest is None:
             continue
@@ -138,6 +179,11 @@ def verify_versions(
                 f"{label} manifest version must increase relative to {base_ref}: "
                 f"{base_manifest.get('version')} -> {current_versions.get(label)}"
             )
+    if base_manifest_count == 0:
+        errors.append(
+            f"no synchronized plugin manifest exists at {base_ref}; "
+            "cannot establish that the package version advanced"
+        )
 
 
 def verify_manifest_identity(manifests: dict[str, dict[str, Any]], errors: list[str]) -> None:
@@ -146,20 +192,40 @@ def verify_manifest_identity(manifests: dict[str, dict[str, Any]], errors: list[
             errors.append(
                 f"{label} manifest name must remain {PLUGIN_NAME!r}; got {payload.get('name')!r}"
             )
+    reference_label = next(iter(MANIFEST_PATHS))
+    reference = manifests[reference_label]
+    for label, payload in manifests.items():
+        if label == reference_label:
+            continue
+        for field in SHARED_MANIFEST_FIELDS:
+            if payload.get(field) != reference.get(field):
+                errors.append(
+                    f"{label} manifest {field!r} must match {reference_label}; "
+                    f"got {payload.get(field)!r}"
+                )
 
 
 def verify_marketplaces(root: Path, errors: list[str]) -> None:
     claude_marketplace = load_json(root / CLAUDE_MARKETPLACE, errors)
     codex_marketplace = load_json(root / CODEX_MARKETPLACE, errors)
-    if claude_marketplace is None or codex_marketplace is None:
+    factory_marketplace = load_json(root / FACTORY_MARKETPLACE, errors)
+    if (
+        claude_marketplace is None
+        or codex_marketplace is None
+        or factory_marketplace is None
+    ):
         return
 
     claude_entry = find_plugin_entry(claude_marketplace, "Claude", errors)
     codex_entry = find_plugin_entry(codex_marketplace, "Codex", errors)
-    if claude_entry is None or codex_entry is None:
+    factory_entry = find_plugin_entry(factory_marketplace, "Factory", errors)
+    if claude_entry is None or codex_entry is None or factory_entry is None:
         return
 
     claude_root = resolve_local_path(root, claude_entry.get("source"), "Claude plugin source", errors)
+    factory_root = resolve_local_path(
+        root, factory_entry.get("source"), "Factory plugin source", errors
+    )
 
     codex_source = codex_entry.get("source")
     if not isinstance(codex_source, dict) or codex_source.get("source") != "local":
@@ -183,15 +249,26 @@ def verify_marketplaces(root: Path, errors: list[str]) -> None:
         errors.append("Claude marketplace target does not contain .claude-plugin/plugin.json")
     if codex_root is not None and not (codex_root / MANIFEST_PATHS["Codex"]).is_file():
         errors.append("Codex marketplace target does not contain .codex-plugin/plugin.json")
-    if claude_root is not None and codex_root is not None and claude_root != codex_root:
-        errors.append("Claude and Codex marketplaces must package the same plugin root")
+    if factory_root is not None and not (factory_root / MANIFEST_PATHS["Factory"]).is_file():
+        errors.append("Factory marketplace target does not contain .factory-plugin/plugin.json")
 
-    plugin_root = codex_root or claude_root
+    plugin_roots = [
+        plugin_root
+        for plugin_root in (claude_root, codex_root, factory_root)
+        if plugin_root is not None
+    ]
+    if plugin_roots and any(plugin_root != plugin_roots[0] for plugin_root in plugin_roots[1:]):
+        errors.append("Claude, Codex, and Factory marketplaces must package the same plugin root")
+
+    plugin_root = codex_root or claude_root or factory_root
     if plugin_root is None:
         return
     skill = plugin_root / "skills" / PLUGIN_NAME / "SKILL.md"
     if not skill.is_file():
         errors.append(f"packaged skill is missing: {skill.relative_to(root)}")
+    commands = plugin_root / "commands"
+    if not commands.is_dir() or not any(commands.glob("*.md")):
+        errors.append("packaged commands are missing from the shared plugin root")
 
 
 def verify_codex_skill_path(root: Path, codex_manifest: dict[str, Any], errors: list[str]) -> None:
@@ -232,7 +309,7 @@ def main() -> int:
         return 1
     versions = load_json(ROOT / MANIFEST_PATHS["Claude"], [])["version"]
     print(
-        f"OK plugin package: Claude and Codex {versions}, "
+        f"OK plugin package: Claude, Codex, and Factory {versions}, "
         f"marketplace paths, and packaged skill"
     )
     return 0