@tyroneross/build-loop 0.36.1 → 0.43.0

package/skills/native-ax-driver/scripts/native_driver.py

@@ -14,10 +14,10 @@ synthetic mouse or keyboard events — the user's hardware cursor is never moved
 Usage (from a build-loop run, project cwd):
 
     # Resolve a running app to its pid (no AX permission needed for this)
-    python3 native_driver.py resolve --app "Secrets Vault"
+    python3 native_driver.py resolve --app "MyApp"
 
     # Scan AX tree of running app
-    python3 native_driver.py scan --app "Secrets Vault" --json
+    python3 native_driver.py scan --app "MyApp" --json
     python3 native_driver.py scan --pid 12345 --json
 
     # Perform an AX action on a specific element
@@ -34,6 +34,11 @@ Usage (from a build-loop run, project cwd):
     # List running regular GUI apps (no AX permission needed)
     python3 native_driver.py apps
 
+    # Launch an isolated instance under a private state dir and capture its pid
+    # (see SKILL.md "Single-instance PID-scoped verification mode")
+    python3 native_driver.py launch --app-path /Applications/MyApp.app \\
+        --state-env-var ET_STATE_DIR --state-dir /tmp/myapp-verify --fresh
+
     # Analyze a captured AX tree for centered-narrow layout gaps
     python3 native_driver.py analyze-layout --stdin < ax-tree.json
 
@@ -49,6 +54,7 @@ import os
 import shutil
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 # ─── Paths ────────────────────────────────────────────────────────────────────
@@ -180,28 +186,33 @@ def cmd_preflight(_args: argparse.Namespace) -> int:
         return 2
 
 
-def cmd_apps(_args: argparse.Namespace) -> int:
-    """List regular GUI apps with their pid and bundle identifier (no AX needed)."""
+def _query_gui_processes() -> list[dict]:
+    """Query System Events for every foreground GUI process: name, pid, bundle id.
+
+    Raises FileNotFoundError (no osascript) or subprocess.CalledProcessError
+    (AppleScript failed) — callers decide how to surface those.
+    """
+    # Fetch each property as its own list and concatenate — a record
+    # (`{name, unix id, ...} of ...`) or a bound variable holding the filtered
+    # collection both raise -1728 on current macOS; the direct per-property form
+    # is the reliable one. Restrict to `application processes` (not `every
+    # process`): background-only daemons lack a `background only` property and
+    # error the filter. Order (names, pids, bundles) matches the flat-thirds
+    # parser below.
+    proc_set = "(application processes whose background only is false)"
     script = (
-        'tell application "System Events" to '
-        'get {name, unix id, bundle identifier} of every process '
-        "whose background only is false"
+        'tell application "System Events" to return '
+        f"(name of {proc_set}) & "
+        f"(unix id of {proc_set}) & "
+        f"(bundle identifier of {proc_set})"
+    )
+    result = subprocess.run(
+        ["osascript", "-e", script],
+        capture_output=True,
+        text=True,
+        timeout=10,
+        check=True,
     )
-    try:
-        result = subprocess.run(
-            ["osascript", "-e", script],
-            capture_output=True,
-            text=True,
-            timeout=10,
-            check=True,
-        )
-    except FileNotFoundError:
-        print(json.dumps({"error": "osascript missing"}), file=sys.stderr)
-        return 1
-    except subprocess.CalledProcessError as e:
-        print(json.dumps({"error": e.stderr.strip() or "osascript failed"}), file=sys.stderr)
-        return 1
-
     raw = result.stdout.strip()
     # AppleScript returns a flat list: name1, name2, ..., pid1, pid2, ..., bundle1, ...
     parts = [p.strip() for p in raw.split(",")]
@@ -215,6 +226,41 @@ def cmd_apps(_args: argparse.Namespace) -> int:
                 "bundleIdentifier": parts[2 * n + i] if parts[2 * n + i] != "missing value" else None,
             }
         )
+    return apps
+
+
+def _gui_pids(bundle_id: str | None = None) -> set[int]:
+    """Pid set of running GUI processes, optionally filtered to a bundle id.
+
+    Swallows osascript failures and returns an empty set — callers that need
+    to distinguish "no processes" from "query failed" should call
+    `_query_gui_processes()` directly instead.
+    """
+    try:
+        apps = _query_gui_processes()
+    except (FileNotFoundError, subprocess.CalledProcessError, subprocess.TimeoutExpired):
+        return set()
+    pids: set[int] = set()
+    for app in apps:
+        if app["pid"] is None:
+            continue
+        if bundle_id is not None and app.get("bundleIdentifier") != bundle_id:
+            continue
+        pids.add(app["pid"])
+    return pids
+
+
+def cmd_apps(_args: argparse.Namespace) -> int:
+    """List regular GUI apps with their pid and bundle identifier (no AX needed)."""
+    try:
+        apps = _query_gui_processes()
+    except FileNotFoundError:
+        print(json.dumps({"error": "osascript missing"}), file=sys.stderr)
+        return 1
+    except subprocess.CalledProcessError as e:
+        print(json.dumps({"error": e.stderr.strip() or "osascript failed"}), file=sys.stderr)
+        return 1
+
     print(json.dumps(apps, indent=2))
     return 0
 
@@ -234,6 +280,185 @@ def cmd_resolve(args: argparse.Namespace) -> int:
     return 0
 
 
+def select_new_pid(before: set[int], after: set[int]) -> int | None:
+    """Return the single new pid in `after - before`, or None if 0 or >1.
+
+    Pure and deterministic — the caller must treat None as "ambiguous, do
+    not guess" rather than picking an arbitrary candidate.
+    """
+    new = after - before
+    if len(new) == 1:
+        return next(iter(new))
+    return None
+
+
+def build_launch_env(base_env: dict, state_env_var: str | None, state_dir: str | None) -> dict:
+    """Return a COPY of base_env with state_env_var=state_dir set, iff both given.
+
+    Never mutates base_env.
+    """
+    env = dict(base_env)
+    if state_env_var and state_dir:
+        env[state_env_var] = state_dir
+    return env
+
+
+def build_open_command(
+    target: str, *, by_bundle_id: bool, fresh: bool, args: list[str]
+) -> list[str]:
+    """Build the macOS `open` argv for an isolated-instance launch.
+
+    Always forces a new instance (`-n`). Adds `-F` (ignore saved window/scene
+    state) when `fresh` — never wedge into the app's saved state from a prior
+    run. Targets by bundle id (`-b`) or by `.app` path. `--args` is only
+    appended when there are extra argv to pass through.
+    """
+    cmd = ["open", "-n"]
+    if fresh:
+        cmd.append("-F")
+    if by_bundle_id:
+        cmd += ["-b", target]
+    else:
+        cmd.append(target)
+    if args:
+        cmd.append("--args")
+        cmd += list(args)
+    return cmd
+
+
+def _derive_bundle_id(app_path: str) -> str | None:
+    """Best-effort CFBundleIdentifier lookup from an .app's Info.plist.
+
+    Used only to filter candidate pids and for the launch report — never
+    raises; returns None on any failure (missing `defaults`, malformed
+    bundle, timeout).
+    """
+    info_plist_prefix = str(Path(app_path) / "Contents" / "Info")
+    try:
+        result = subprocess.run(
+            ["defaults", "read", info_plist_prefix, "CFBundleIdentifier"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    bundle_id = result.stdout.strip()
+    return bundle_id or None
+
+
+def cmd_launch(args: argparse.Namespace) -> int:
+    """Launch an isolated app instance under a private state dir and capture its pid.
+
+    This is the deterministic launch + pid-capture half of the "single-instance
+    PID-scoped verification mode" (see SKILL.md). It never assumes which pid
+    belongs to the new instance — it snapshots the running GUI pid set before
+    launch, launches with `open -n` (always a new instance), and diffs the
+    pid set after launch. Ambiguous results (zero or more than one new pid)
+    are reported as failure rather than guessed.
+    """
+    if bool(args.app_path) == bool(args.bundle_id):
+        # The argparse mutually-exclusive required group should prevent this;
+        # guard defensively so a programmatic caller gets a clean error too.
+        print(
+            json.dumps(
+                {
+                    "success": False,
+                    "pid": None,
+                    "error": "exactly one of --app-path/--bundle-id required",
+                }
+            ),
+            file=sys.stderr,
+        )
+        return 2
+
+    if args.bundle_id:
+        target = args.bundle_id
+        by_bundle_id = True
+        bundle_id = args.bundle_id
+    else:
+        target = str(args.app_path)
+        by_bundle_id = False
+        bundle_id = _derive_bundle_id(target)
+
+    def _fail(error: str) -> int:
+        print(
+            json.dumps(
+                {
+                    "success": False,
+                    "pid": None,
+                    "bundle_id": bundle_id,
+                    "state_dir": args.state_dir,
+                    "fresh": args.fresh,
+                    "error": error,
+                    "next": None,
+                }
+            )
+        )
+        return 1
+
+    # A failed before-snapshot is a HARD launch failure, not an empty baseline.
+    # _gui_pids() swallows query errors into an empty set; if we used it here and
+    # the osascript query failed while the user had one ambient instance running,
+    # the after-poll would surface that ambient pid as "new" and we would drive
+    # the user's live window — the exact failure this mode exists to prevent.
+    try:
+        before = {
+            app["pid"]
+            for app in _query_gui_processes()
+            if app["pid"] is not None
+        }
+    except (FileNotFoundError, subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
+        return _fail(f"could not snapshot GUI pids before launch: {e}")
+    env = build_launch_env(dict(os.environ), args.state_env_var, args.state_dir)
+    open_argv = build_open_command(
+        target, by_bundle_id=by_bundle_id, fresh=args.fresh, args=args.args or []
+    )
+
+    try:
+        proc = subprocess.run(open_argv, env=env, capture_output=True, text=True, timeout=15)
+    except (subprocess.TimeoutExpired, FileNotFoundError) as e:
+        return _fail(f"`open` failed to run: {e}")
+
+    if proc.returncode != 0:
+        return _fail(proc.stderr.strip() or f"open exited {proc.returncode}")
+
+    deadline = time.monotonic() + args.timeout
+    pid: int | None = None
+    while time.monotonic() < deadline:
+        after = _gui_pids(bundle_id=bundle_id)
+        pid = select_new_pid(before, after)
+        if pid is not None:
+            break
+        time.sleep(0.25)
+
+    if pid is None:
+        return _fail(
+            "could not capture a single new pid (zero or ambiguous candidates) "
+            "within timeout"
+        )
+
+    print(
+        json.dumps(
+            {
+                "success": True,
+                "pid": pid,
+                "bundle_id": bundle_id,
+                "state_dir": args.state_dir,
+                "fresh": args.fresh,
+                "error": None,
+                "next": (
+                    f"drive AX scoped to this pid: native_driver.py scan --pid {pid} "
+                    f"/ action --pid {pid} ..."
+                ),
+            }
+        )
+    )
+    return 0
+
+
 def cmd_scan(args: argparse.Namespace) -> int:
     binary = ensure_binary()
     cmd: list[str] = [str(binary)]
@@ -440,6 +665,36 @@ def build_parser() -> argparse.ArgumentParser:
     p_resolve = sub.add_parser("resolve", help="Resolve an app name to its pid")
     p_resolve.add_argument("--app", required=True)
 
+    p_launch = sub.add_parser(
+        "launch",
+        help="Launch an isolated app instance under a private state dir and capture its pid",
+    )
+    launch_target = p_launch.add_mutually_exclusive_group(required=True)
+    launch_target.add_argument("--app-path", help="Path to a .app bundle")
+    launch_target.add_argument("--bundle-id", help="Bundle identifier, e.g. com.example.myapp")
+    p_launch.add_argument("--state-dir", help="Isolated state directory for this instance")
+    p_launch.add_argument(
+        "--state-env-var",
+        help="Env var name to point at --state-dir, e.g. ET_STATE_DIR",
+    )
+    p_launch.add_argument(
+        "--fresh",
+        action="store_true",
+        help="Pass -F to `open` (ignore saved window/scene state)",
+    )
+    p_launch.add_argument(
+        "--arg",
+        action="append",
+        dest="args",
+        help="Extra argv passed through to the launched app (repeatable)",
+    )
+    p_launch.add_argument(
+        "--timeout",
+        type=float,
+        default=10.0,
+        help="Seconds to wait for the new pid to appear (default 10.0)",
+    )
+
     p_scan = sub.add_parser("scan", help="Scan AX tree of running app")
     p_scan.add_argument("--pid", type=int)
     p_scan.add_argument("--app")
@@ -479,6 +734,7 @@ def main(argv: list[str] | None = None) -> int:
         "preflight": cmd_preflight,
         "apps": cmd_apps,
         "resolve": cmd_resolve,
+        "launch": cmd_launch,
         "scan": cmd_scan,
         "analyze-layout": cmd_analyze_layout,
         "action": cmd_action,

package/skills/native-ax-driver/scripts/test_native_driver.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""
+Tests for the pure launch / pid-capture / scope-selection helpers in
+native_driver.py.
+
+Honest scope: the live path — `launch` actually invoking macOS `open`,
+snapshotting real GUI process pids via osascript, and driving the Swift AX
+binary against the captured pid — requires a running macOS GUI session and
+Accessibility permission. That path cannot be exercised headlessly and is
+NOT unit-tested here; it is covered by the SKILL.md manual self-test
+("Single-instance PID-scoped verification mode").
+
+What IS tested here is the pure, deterministic logic that decides which pid
+belongs to the freshly-launched instance and how the `open` invocation is
+built — the part that must never guess. These functions take no OS action
+and have no side effects, so they run anywhere pytest runs.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+
+import pytest
+
+import native_driver
+
+
+# ─── select_new_pid ────────────────────────────────────────────────────────
+
+
+def test_select_new_pid_single_new_pid():
+    assert native_driver.select_new_pid({1, 2}, {1, 2, 3}) == 3
+
+
+def test_select_new_pid_identical_sets_returns_none():
+    assert native_driver.select_new_pid({1, 2}, {1, 2}) is None
+
+
+def test_select_new_pid_two_new_pids_is_ambiguous():
+    assert native_driver.select_new_pid({1, 2}, {1, 2, 3, 4}) is None
+
+
+def test_select_new_pid_empty_before_one_after():
+    assert native_driver.select_new_pid(set(), {42}) == 42
+
+
+def test_select_new_pid_empty_before_empty_after():
+    assert native_driver.select_new_pid(set(), set()) is None
+
+
+def test_select_new_pid_pid_disappeared_is_not_new():
+    # before has a pid that's gone in after; no new pid appeared.
+    assert native_driver.select_new_pid({1, 2, 3}, {1, 2}) is None
+
+
+# ─── build_launch_env ──────────────────────────────────────────────────────
+
+
+def test_build_launch_env_sets_key_when_both_given():
+    base = {"PATH": "/usr/bin"}
+    env = native_driver.build_launch_env(base, "ET_STATE_DIR", "/tmp/state")
+    assert env["ET_STATE_DIR"] == "/tmp/state"
+    assert env["PATH"] == "/usr/bin"
+
+
+def test_build_launch_env_does_not_mutate_input():
+    base = {"PATH": "/usr/bin"}
+    native_driver.build_launch_env(base, "ET_STATE_DIR", "/tmp/state")
+    assert base == {"PATH": "/usr/bin"}
+    assert "ET_STATE_DIR" not in base
+
+
+def test_build_launch_env_no_state_env_var_returns_unchanged_copy():
+    base = {"PATH": "/usr/bin"}
+    env = native_driver.build_launch_env(base, None, "/tmp/state")
+    assert env == base
+    assert env is not base
+
+
+def test_build_launch_env_no_state_dir_returns_unchanged_copy():
+    base = {"PATH": "/usr/bin"}
+    env = native_driver.build_launch_env(base, "ET_STATE_DIR", None)
+    assert env == base
+    assert env is not base
+
+
+def test_build_launch_env_both_none_returns_unchanged_copy():
+    base = {"PATH": "/usr/bin"}
+    env = native_driver.build_launch_env(base, None, None)
+    assert env == base
+    assert env is not base
+
+
+# ─── build_open_command ────────────────────────────────────────────────────
+
+
+def test_build_open_command_always_includes_force_new_instance():
+    cmd = native_driver.build_open_command(
+        "/Applications/MyApp.app", by_bundle_id=False, fresh=False, args=[]
+    )
+    assert "-n" in cmd
+
+
+def test_build_open_command_fresh_true_includes_dash_F():
+    cmd = native_driver.build_open_command(
+        "/Applications/MyApp.app", by_bundle_id=False, fresh=True, args=[]
+    )
+    assert "-F" in cmd
+
+
+def test_build_open_command_fresh_false_excludes_dash_F():
+    cmd = native_driver.build_open_command(
+        "/Applications/MyApp.app", by_bundle_id=False, fresh=False, args=[]
+    )
+    assert "-F" not in cmd
+
+
+def test_build_open_command_by_bundle_id_uses_dash_b():
+    cmd = native_driver.build_open_command(
+        "com.example.myapp", by_bundle_id=True, fresh=False, args=[]
+    )
+    assert "-b" in cmd
+    assert cmd[cmd.index("-b") + 1] == "com.example.myapp"
+    assert "com.example.myapp" not in cmd[: cmd.index("-b")]
+
+
+def test_build_open_command_by_app_path_uses_raw_path():
+    cmd = native_driver.build_open_command(
+        "/Applications/MyApp.app", by_bundle_id=False, fresh=False, args=[]
+    )
+    assert "-b" not in cmd
+    assert "/Applications/MyApp.app" in cmd
+
+
+def test_build_open_command_appends_args_when_nonempty():
+    cmd = native_driver.build_open_command(
+        "/Applications/MyApp.app",
+        by_bundle_id=False,
+        fresh=False,
+        args=["--flag", "value"],
+    )
+    assert "--args" in cmd
+    idx = cmd.index("--args")
+    assert cmd[idx + 1 :] == ["--flag", "value"]
+
+
+def test_build_open_command_no_args_omits_dash_dash_args():
+    cmd = native_driver.build_open_command(
+        "/Applications/MyApp.app", by_bundle_id=False, fresh=False, args=[]
+    )
+    assert "--args" not in cmd
+
+
+def test_build_open_command_full_shape_fresh_bundle_with_args():
+    cmd = native_driver.build_open_command(
+        "com.example.myapp",
+        by_bundle_id=True,
+        fresh=True,
+        args=["--seed", "123"],
+    )
+    assert cmd == ["open", "-n", "-F", "-b", "com.example.myapp", "--args", "--seed", "123"]
+
+
+# ─── cmd_launch before-snapshot safety (auditor finding f1) ─────────────────
+#
+# The one path where this mode could hand back the USER's pid: if the
+# before-snapshot query fails, an empty baseline makes a lone ambient pid look
+# "new". cmd_launch must treat a failed before-snapshot as a HARD launch
+# failure and NEVER invoke `open`.
+
+
+def test_cmd_launch_hard_fails_when_before_snapshot_query_errors(monkeypatch, capsys):
+    import argparse
+    import subprocess as _subprocess
+
+    def _raise(*_a, **_k):
+        raise _subprocess.CalledProcessError(1, ["osascript"], stderr="boom")
+
+    monkeypatch.setattr(native_driver, "_query_gui_processes", _raise)
+
+    # If `open` (or any subprocess) is invoked, the guard failed — fail loudly.
+    def _forbidden(*_a, **_k):
+        raise AssertionError("cmd_launch invoked a subprocess despite a failed before-snapshot")
+
+    monkeypatch.setattr(native_driver.subprocess, "run", _forbidden)
+
+    args = argparse.Namespace(
+        app_path=None,
+        bundle_id="com.example.myapp",
+        state_dir=None,
+        state_env_var=None,
+        fresh=False,
+        args=[],
+        timeout=1.0,
+    )
+    rc = native_driver.cmd_launch(args)
+    out = capsys.readouterr().out
+    assert rc == 1
+    payload = json.loads(out)
+    assert payload["success"] is False
+    assert "snapshot" in payload["error"].lower()
+
+
+@pytest.mark.skipif(
+    shutil.which("osascript") is None,
+    reason="live osascript smoke — requires a macOS GUI session; skipped headless",
+)
+def test_query_gui_processes_live_smoke():
+    """Invoke the REAL osascript query, not a mock.
+
+    The mocked unit tests above cannot validate the AppleScript STRING — which
+    is exactly how a malformed multi-property query (`{name, unix id, bundle
+    identifier} of every process whose ...`) shipped and raised -1728 at
+    runtime (2026-07-19), leaving `_gui_pids()` empty and the PID-scoped launch
+    non-functional while every unit test stayed green. This asserts the query
+    actually parses and returns a plausible process list on a real macOS
+    session; it skips cleanly in headless CI.
+    """
+    apps = native_driver._query_gui_processes()
+    assert isinstance(apps, list)
+    assert apps, "no GUI processes returned — the AppleScript query is likely malformed"
+    for a in apps:
+        assert {"name", "pid", "bundleIdentifier"} <= set(a)
+    assert any(a["pid"] for a in apps), "no real pids captured — launch pid-capture would fail"

package/skills/optimize/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: optimize
 description: Use when the user says "optimize this", "optimization", "make X faster", "reduce <metric>", or "speed up my app". Runs a Design of Experiments test matrix — up to 6 variables in one pass — to find which variable actually moves the number. Falls back to one-at-a-time loop for single variables.
-user-invocable: true
+user-invocable: false
 ---
 
 <!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->

package/skills/plugin-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plugin-builder
-description: Use when the user asks to create, build, scaffold, convert, or migrate a Claude Code plugin, or needs guidance on plugin.json, directory layout, hooks, MCP servers, agents, LSP, or distribution.
+description: Create, scaffold, or migrate a Claude Code plugin — manifest, directory layout, hooks, agents, distribution. Use when the user asks to create/build/scaffold/convert a plugin, or needs plugin.json/layout guidance. Not for building the MCP server itself once the shell exists (use `mcp-builder`; pair the two).
 user-invocable: false
 ---
 
@@ -327,3 +327,50 @@ Core references (load as needed — don't pre-load all):
 Related skills:
 - **`mcp-builder`** — MCP server implementation companion
 - **`skill-builder`** — SKILL.md authoring (for skills shipped inside a plugin)
+
+## Distribution & versioning — DETECT, don't mandate
+
+Before touching any `version` field, run the detector:
+
+```bash
+python3 scripts/detect_plugin_distribution.py <repo> --hub <fleet marketplace.json>
+```
+
+The install SOURCE decides the policy (auto-SHA vs semver) — a blanket rule gets it wrong.
+What is NOT negotiable is *consistency*: the version state must agree across `plugin.json`,
+the codex manifest, and the marketplace entry, or one silently masks the others. Enforce that
+invariant in CI with either of two equivalent options:
+
+**Option A — local check (default; no external dependency).** `detect_plugin_distribution.py`
+itself is advisory-only (always exits 0, prints a recommendation) — it is not a gate as
+shipped. Vendor the script into the generated repo and wrap its `--json` output in a CI step
+that fails on the `consistent` field:
+
+```yaml
+jobs:
+  verify-manifests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: |
+          python3 scripts/detect_plugin_distribution.py . --json > /tmp/dist.json
+          python3 -c "import json,sys; d=json.load(open('/tmp/dist.json')); sys.exit(0 if d['consistent'] else 1)"
+```
+
+(Adjust the script path to wherever `detect_plugin_distribution.py` lands in the generated
+repo — vendor the script itself, not just the CI call.)
+
+**Option B — reuse the maintainer's shared workflow (opt-in, explicit dependency).** build-loop's
+own CI calls a reusable workflow hosted in the maintainer's `tyroneross/RossLabs-AI-Toolkit` repo
+at the `plugin-ci-v1` tag. This is convenient but puts the generated repo's CI at the mercy of a
+third-party org: if that repo goes private, is renamed, or the tag is force-moved/deleted, the
+generated repo's CI breaks with no local fallback. Only wire this in if the user explicitly wants
+to track the maintainer's shared workflow and understands that risk:
+
+```yaml
+jobs:
+  verify-manifests:
+    uses: tyroneross/RossLabs-AI-Toolkit/.github/workflows/verify-plugin-manifests.yml@plugin-ci-v1
+```
+
+Full decision table + the failure that motivated it: `references/plugin-distribution.md`.

package/skills/plugin-builder/references/build-loop-phase-guidance.md

@@ -73,10 +73,10 @@ The rename is a full migration, not a metadata change. Partial renames produce p
 ## Source-of-truth flow
 
 ```
-~/Desktop/git-folder/<plugin-repo>/            ← author-owned, edit here, commit
+<your-local-checkout>/<plugin-repo>/           ← author-owned, edit here, commit
        │
        ▼ (git push)
-GitHub: tyroneross/<marketplace>/              ← marketplace pulls from here
+GitHub: <your-github-org>/<marketplace>/       ← marketplace pulls from here
        │
        ▼ (plugin sync)
 ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/   ← generated, never edit long-term
@@ -90,5 +90,4 @@ Build-loop must edit the source repo, not the cache. Cache edits survive until t
 ## References
 
 - `~/.claude/skills/plugin-builder/references/plugin-hygiene-lessons.md` — full incident log
-- `~/.claude/projects/-Users-tyroneross/memory/feedback_hook_design.md` — hook design rules
-- `~/.claude/projects/-Users-tyroneross/memory/feedback_rosslabs_toolkit_sync.md` — marketplace rename sync
+- Per-project Claude Code memory (`feedback_hook_design.md`, `feedback_rosslabs_toolkit_sync.md`) — hook design rules and marketplace-rename-sync notes, when present. These live under a project-slug directory in `~/.claude/projects/` derived from your home path (glob `~/.claude/projects/-Users-*/memory/` to find yours); they are optional, personal notes, not part of this plugin.