td-ai-tools 1.3.6 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

package/skills/README.md

@@ -2,13 +2,13 @@
 
 ## Available Skills
 - `a11y-audit`: Run script-driven accessibility audits for user-provided URLs with Axe Core and Playwright, targeting…
-- `barrage`: Convert a group of Basecamp todos or cards into a td-barrage queue.json task file.
+- `barrage`: Convert a group of Basecamp todos or cards into a td-barrage queue.json task file, and maintain an existing…
 - `basecamp`: Interact with Basecamp via the Basecamp CLI.
 - `browser-validation`: Before completing a task validate frontend or template changes in a real browser with the Playwright-CLI…
 - `cache-reset`: Clear and warm Laravel and Statamic caches (including Statamic Glide image caches) after content or template…
 - `client-overview`: Generate a client-facing markdown report that summarizes all changes on the current branch against the…
 - `debugging-ios-webkit`: Debugs iOS Safari/Chrome-iOS rendering bugs — stale paints, viewport/browser-chrome clipping, mobile-only CSS…
-- `forge-cli`: Manage Laravel Forge servers, sites, and provisioned resources from the terminal with the Laravel Forge CLI,…
+- `forge-cli`: Manage Laravel Forge organizations, servers, sites, and provisioned resources with Forge CLI 2.x, falling…
 - `horizon-component-migration`: Bundle Shopify Horizon components into a migration package for a different theme, including recursive…
 - `playwright-cli`: Automates browser interactions for web testing, screenshots, and data extraction.
 - `pr-solver`: Resolve GitHub pull request feedback by querying unresolved review conversations with the GitHub GraphQL API…

package/skills/barrage/SKILL.md

@@ -2,18 +2,24 @@
 name: barrage
 description: |
   Convert a group of Basecamp todos or cards into a td-barrage queue.json task
-  file. Fetches the items via the Basecamp CLI, maps each title -> task id and
-  description -> prompt, and writes queue.json into this skill's directory. Use
-  when the user wants to turn Basecamp work into a barrage queue, build a
-  td-barrage queue from Basecamp, or run a todolist/card table through td-barrage.
+  file, and maintain an existing queue. Fetches the items via the Basecamp CLI,
+  maps each title -> task id and description -> prompt, and writes queue.json into
+  the `.agents` copy of this skill (one shared queue, whichever install runs).
+  Also resets tasks to 0 attempts so they run again, and deletes all tasks from a
+  queue. Use when the user wants to turn Basecamp work
+  into a barrage queue, build a td-barrage queue from Basecamp, run a
+  todolist/card table through td-barrage, reset/retry queue tasks, or clear/empty
+  a barrage queue.
 invocable: true
-argument-hint: "[basecamp todolist/card-table/column URL] [--timeout-mins N]"
+argument-hint: "[basecamp todolist/card-table/column URL] [--timeout-mins N] | reset | clear"
 ---
 
 # /barrage — Basecamp → td-barrage queue builder
 
 Turns a user-specified group of Basecamp todos or cards into a `queue.json` in the
-format consumed by **td-barrage**, a batch task runner (see
+format consumed by **td-barrage**, a batch task runner, and maintains that file
+afterwards (see [Maintaining an existing queue](#maintaining-an-existing-queue)
+for resetting attempts and clearing tasks; see
 [Output: the td-barrage queue.json format](#output-the-td-barrage-queuejson-format)
 below for the full schema — this skill emits that format directly and needs no
 other repo installed).
@@ -50,9 +56,15 @@ Each Basecamp item becomes one td-barrage task:
 > `timeoutMs` (**milliseconds**), and `maxAttempts` — this skill emits the real
 > field names (documented in full below).
 
-The file is written to **this skill's directory** as `queue.json`
-(`build_queue.py` resolves that path from its own location, so it lands next to the
-script regardless of which skills copy is invoked).
+The file is written to `.agents/skills/barrage/queue.json` — the **`.agents` copy
+of this skill**, regardless of which copy is running. The toolkit installs the skill
+into every configured agent root (`.claude/`, `.agents/`, …), each with its own
+scripts; routing every write to `.agents` keeps one shared queue instead of a
+per-agent one, so td-barrage always runs the file you just built. If there is no
+`.agents/` directory beside the running copy (or the skill is not laid out as
+`<root>/skills/barrage/`, as in the toolkit source checkout), the queue falls back
+to the running copy's own directory. `scripts/queue_paths.py` holds that rule; both
+scripts default to it and `--output` / `--queue` still override it.
 
 ## Workflow
 
@@ -111,21 +123,65 @@ basecamp todos list --list <id> --in <proj> --json \
 ```
 
 `$SKILL_DIR` is the directory containing this `SKILL.md`. The script writes
-`queue.json` into that directory and prints a summary plus any per-item warnings
-(skipped items with no description, deduped ids, etc.).
+`queue.json` into the `.agents` copy of the skill (see above) and prints a summary
+plus any per-item warnings (skipped items with no description, deduped ids, etc.).
+`--help` shows the resolved path.
 
 Options:
 
 - `--timeout-mins N` — override the 35-minute default (the script converts to ms).
 - `--max-attempts N` — override the default of 2.
 - `--keep-estimate` — keep the `[Nh]` suffix in the id instead of stripping it.
-- `--output PATH` — write somewhere other than `<skill>/queue.json`.
+- `--output PATH` — write somewhere other than the shared `.agents` queue.
 
 ### 5. Report
 
 Tell the user where `queue.json` was written, how many tasks it contains, and
 surface any warnings the script printed (skipped or renamed items).
 
+## Maintaining an existing queue
+
+`scripts/manage_queue.py` edits a queue file in place — use it when the user asks
+to retry/reset tasks or to empty the queue. Both subcommands default to the same
+shared `.agents/skills/barrage/queue.json` that `build_queue.py` writes; pass
+`--queue PATH` for a queue elsewhere. Both write a
+`<queue>.bak` copy first (`--no-backup` opts out) and preserve the file's
+top-level shape (`{"tasks": [...]}` stays an object, a bare `[...]` stays an array).
+
+### Reset tasks to 0 attempts
+
+```bash
+python3 "$SKILL_DIR/scripts/manage_queue.py" reset
+```
+
+By default this is a **full re-run reset**: `attempts` → `0`, `status` →
+`pending`, and the runtime fields `error` / `startedAt` / `finishedAt` are
+dropped. Zeroing `attempts` alone is not enough — td-barrage skips any task whose
+status is already `done` or `failed`, so the status reset is what actually makes
+the task run again. Authored fields (`prompt`, `dependsOn`, `maxAttempts`,
+`timeoutMs`, `cwd`, `success`) and the `recoveryNotes` history are untouched.
+
+- `--status STATUS` — only reset tasks in that status (repeatable). `--status failed`
+  is the common case: retry the failures and leave completed work alone.
+- `--attempts-only` — zero `attempts` and change nothing else (the literal, narrow
+  reset; the task still will not re-run if its status is `done` or `failed`).
+- `--dry-run` — print the per-task changes without writing.
+
+The script prints one line per changed task (`<id>: attempts 2 -> 0, status failed
+-> pending`); relay that summary.
+
+### Delete all tasks
+
+```bash
+python3 "$SKILL_DIR/scripts/manage_queue.py" clear --yes
+```
+
+Empties the `tasks` array, leaving a valid but empty queue file. `--yes` is
+**required**: without it the command only reports how many tasks it would delete
+and exits non-zero without writing. Run it bare first to show the user the count,
+then re-run with `--yes` once they confirm. The pre-clear queue is recoverable
+from `<queue>.bak`.
+
 ## Output: the td-barrage queue.json format
 
 td-barrage validates the file with a Zod schema. This skill emits the minimal

package/skills/barrage/scripts/build_queue.py

@@ -33,6 +33,15 @@ from typing import Any
 # Skill root is the parent of this script's directory (scripts/ -> <skill>/).
 SKILL_DIR = Path(__file__).resolve().parent.parent
 
+# Importable whether this file is run as a script or loaded by path (tests).
+if str(Path(__file__).resolve().parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+from queue_paths import resolve_queue_path  # noqa: E402
+
+# The queue is shared across installs: always the `.agents` copy when there is
+# one, whichever copy of the skill is running (see queue_paths.py).
+DEFAULT_QUEUE = resolve_queue_path(SKILL_DIR)
+
 # Matches a trailing estimate suffix like " [2h]" or " [1.5h]" (case-insensitive).
 # Basecamp titles produced by an estimation workflow carry this suffix (the
 # td-augury generator appends "[<hours>h]"); we strip it from the task id so the
@@ -201,8 +210,8 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
     parser.add_argument(
         "--output",
         type=Path,
-        default=SKILL_DIR / "queue.json",
-        help="Where to write the queue file (default: <skill>/queue.json).",
+        default=DEFAULT_QUEUE,
+        help=f"Where to write the queue file (default: {DEFAULT_QUEUE}).",
     )
     parser.add_argument(
         "--timeout-mins",

package/skills/barrage/scripts/manage_queue.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Maintenance tools for an existing td-barrage queue.json.
+
+Two subcommands operate on a queue file in place:
+
+  reset  - zero the attempt counters so tasks can run again. By default this is a
+           full re-run reset: attempts -> 0, status -> "pending", and the runtime
+           fields error/startedAt/finishedAt are dropped (attempts alone is not
+           enough -- td-barrage skips a task whose status is already "done" or
+           "failed"). Pass --attempts-only for the literal, narrow reset.
+  clear  - delete every task, leaving an empty but still-valid queue file.
+
+Both preserve the file's top-level shape: a `{"tasks": [...]}` object stays an
+object, a bare `[...]` array stays an array. The schema is documented in
+../SKILL.md ("Output: the td-barrage queue.json format").
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+# Skill root is the parent of this script's directory (scripts/ -> <skill>/).
+SKILL_DIR = Path(__file__).resolve().parent.parent
+
+# Importable whether this file is run as a script or loaded by path (tests).
+if str(Path(__file__).resolve().parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).resolve().parent))
+from queue_paths import resolve_queue_path  # noqa: E402
+
+# The queue is shared across installs: always the `.agents` copy when there is
+# one, whichever copy of the skill is running (see queue_paths.py).
+DEFAULT_QUEUE = resolve_queue_path(SKILL_DIR)
+
+# The td-barrage task statuses (src/schema.ts: taskStatuses).
+TASK_STATUSES = ("pending", "running", "done", "failed", "blocked")
+
+# Runtime-managed fields cleared by a full reset. `recoveryNotes` is deliberately
+# left alone: it is an append-only history that does not block a re-run.
+_RUNTIME_FIELDS = ("error", "startedAt", "finishedAt")
+
+
+def load_queue(path: Path) -> tuple[Any, list[dict[str, Any]]]:
+    """Return (payload, tasks) where tasks is the live list inside payload."""
+    try:
+        raw = path.read_text()
+    except FileNotFoundError:
+        raise SystemExit(f"Queue file not found: {path}")
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"Failed to parse {path}: {exc}")
+
+    if isinstance(payload, dict) and isinstance(payload.get("tasks"), list):
+        tasks = payload["tasks"]
+    elif isinstance(payload, list):
+        tasks = payload
+    else:
+        raise SystemExit(
+            f"{path} is not a td-barrage queue file "
+            '(expected {"tasks": [...]} or a bare [...] array).'
+        )
+
+    return payload, [task for task in tasks if isinstance(task, dict)]
+
+
+def write_queue(path: Path, payload: Any, tasks: list[dict[str, Any]], *, backup: bool) -> Path | None:
+    """Write `tasks` back into `payload`'s shape. Returns the backup path, if any."""
+    backup_path: Path | None = None
+    if backup and path.exists():
+        backup_path = path.with_suffix(path.suffix + ".bak")
+        shutil.copy2(path, backup_path)
+
+    if isinstance(payload, dict):
+        payload["tasks"] = tasks
+        out: Any = payload
+    else:
+        out = tasks
+
+    path.write_text(json.dumps(out, indent=2) + "\n")
+    return backup_path
+
+
+def reset_tasks(
+    tasks: list[dict[str, Any]],
+    *,
+    attempts_only: bool,
+    statuses: tuple[str, ...] | None,
+) -> list[str]:
+    """Reset matching tasks in place; returns a description per changed task."""
+    changed: list[str] = []
+
+    for task in tasks:
+        status = task.get("status", "pending")
+        if statuses and status not in statuses:
+            continue
+
+        before = dict(task)
+        task["attempts"] = 0
+        if not attempts_only:
+            task["status"] = "pending"
+            for field in _RUNTIME_FIELDS:
+                task.pop(field, None)
+
+        if task != before:
+            was = before.get("attempts", 0)
+            detail = f"attempts {was} -> 0"
+            if not attempts_only and before.get("status", "pending") != "pending":
+                detail += f", status {before['status']} -> pending"
+            changed.append(f"{task.get('id', '<no id>')}: {detail}")
+
+    return changed
+
+
+def cmd_reset(args: argparse.Namespace) -> int:
+    payload, tasks = load_queue(args.queue)
+    if not tasks:
+        print(f"{args.queue} contains no tasks; nothing to reset.")
+        return 0
+
+    statuses = tuple(args.status) if args.status else None
+    changed = reset_tasks(tasks, attempts_only=args.attempts_only, statuses=statuses)
+
+    if not changed:
+        scope = f" with status {', '.join(statuses)}" if statuses else ""
+        print(f"No task{scope} needed resetting in {args.queue}.")
+        return 0
+
+    if args.dry_run:
+        print(f"Would reset {len(changed)} of {len(tasks)} task(s) in {args.queue}:")
+        for line in changed:
+            print(f"  {line}")
+        print("Nothing written (--dry-run).")
+        return 0
+
+    backup_path = write_queue(args.queue, payload, tasks, backup=args.backup)
+    print(f"Reset {len(changed)} of {len(tasks)} task(s) in {args.queue}:")
+    for line in changed:
+        print(f"  {line}")
+    if backup_path:
+        print(f"Backup written to {backup_path}.")
+    return 0
+
+
+def cmd_clear(args: argparse.Namespace) -> int:
+    payload, tasks = load_queue(args.queue)
+    if not tasks:
+        print(f"{args.queue} already contains no tasks.")
+        return 0
+
+    if not args.yes:
+        print(f"Would delete all {len(tasks)} task(s) from {args.queue}.")
+        print("Nothing written — re-run with --yes to apply.", file=sys.stderr)
+        return 1
+
+    backup_path = write_queue(args.queue, payload, [], backup=args.backup)
+    print(f"Deleted all {len(tasks)} task(s) from {args.queue}.")
+    if backup_path:
+        print(f"Backup written to {backup_path}.")
+    return 0
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    def add_common(sub: argparse.ArgumentParser) -> None:
+        sub.add_argument(
+            "--queue",
+            type=Path,
+            default=DEFAULT_QUEUE,
+            help=f"Queue file to modify (default: {DEFAULT_QUEUE}).",
+        )
+        sub.add_argument(
+            "--no-backup",
+            dest="backup",
+            action="store_false",
+            help="Skip writing a <queue>.bak copy before modifying the file.",
+        )
+
+    reset = subparsers.add_parser(
+        "reset",
+        help="Reset tasks to 0 attempts (and back to pending) so they run again.",
+    )
+    add_common(reset)
+    reset.add_argument(
+        "--attempts-only",
+        action="store_true",
+        help="Only zero `attempts`; leave status and error/startedAt/finishedAt alone.",
+    )
+    reset.add_argument(
+        "--status",
+        action="append",
+        choices=TASK_STATUSES,
+        help="Only reset tasks in this status (repeatable; default: all tasks).",
+    )
+    reset.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print what would change without writing the file.",
+    )
+    reset.set_defaults(func=cmd_reset)
+
+    clear = subparsers.add_parser(
+        "clear",
+        help="Delete every task, leaving an empty queue file.",
+    )
+    add_common(clear)
+    clear.add_argument(
+        "--yes",
+        action="store_true",
+        help="Required to actually delete; without it the command only reports.",
+    )
+    clear.set_defaults(func=cmd_clear)
+
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/barrage/scripts/queue_paths.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Resolve the one canonical location for this skill's queue.json.
+
+The toolkit installs the barrage skill into every configured agent root — by
+default both `.claude/skills/barrage/` and `.agents/skills/barrage/`. Each copy
+carries its own scripts, so "write queue.json next to the script" would give
+each agent a private queue and td-barrage would run whichever one happened to be
+built last. Instead `.agents` is treated as the canonical home: whichever copy is
+invoked, the queue is read from and written to the `.agents` one.
+
+Fallbacks (the queue stays next to the running copy) apply when there is no
+`.agents` install to point at, or when the skill is not laid out as
+`<root>/skills/<name>/` — e.g. the toolkit source checkout itself.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# The agent root that owns the shared queue, and the layout every install uses.
+CANONICAL_ROOT = ".agents"
+SKILLS_DIR_NAME = "skills"
+
+QUEUE_FILENAME = "queue.json"
+
+
+def resolve_queue_dir(skill_dir: Path) -> Path:
+    """Return the directory the queue lives in for a skill installed at `skill_dir`."""
+    skill_dir = Path(skill_dir).resolve()
+    if skill_dir.parent.name != SKILLS_DIR_NAME:
+        return skill_dir
+
+    install_root = skill_dir.parent.parent
+    if install_root.name == CANONICAL_ROOT:
+        return skill_dir
+    # A non-dot parent means this is not an installed copy (the toolkit source
+    # checkout, a tarball); there is no project root to hang `.agents` off.
+    if not install_root.name.startswith("."):
+        return skill_dir
+
+    canonical_root = install_root.parent / CANONICAL_ROOT
+    if not canonical_root.is_dir():
+        return skill_dir
+
+    return canonical_root / SKILLS_DIR_NAME / skill_dir.name
+
+
+def resolve_queue_path(skill_dir: Path, filename: str = QUEUE_FILENAME) -> Path:
+    """Return the canonical queue file path for a skill installed at `skill_dir`."""
+    return resolve_queue_dir(skill_dir) / filename

package/skills/barrage/tests/test_manage_queue.py

@@ -0,0 +1,176 @@
+"""Tests for manage_queue.py — the reset / clear queue maintenance tools.
+
+Run: python3 -m pytest .agents/skills/barrage/tests/  (or just `python3 test_manage_queue.py`).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+
+_SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "manage_queue.py"
+_spec = importlib.util.spec_from_file_location("manage_queue", _SCRIPT)
+assert _spec and _spec.loader
+mq = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(mq)
+
+
+# A queue mid-run: one exhausted failure, one success, one untouched task.
+QUEUE = {
+    "tasks": [
+        {
+            "id": "Failed task",
+            "prompt": "do the thing",
+            "status": "failed",
+            "attempts": 2,
+            "maxAttempts": 2,
+            "error": "timed out",
+            "startedAt": "2026-09-11T10:00:00.000Z",
+            "finishedAt": "2026-09-11T10:35:00.000Z",
+        },
+        {"id": "Done task", "prompt": "already done", "status": "done", "attempts": 1},
+        {"id": "Fresh task", "prompt": "not started", "status": "pending", "attempts": 0},
+    ]
+}
+
+
+def write_queue(tmp_path: Path, payload=None) -> Path:
+    path = tmp_path / "queue.json"
+    path.write_text(json.dumps(payload if payload is not None else QUEUE, indent=2))
+    return path
+
+
+def read_tasks(path: Path):
+    data = json.loads(path.read_text())
+    return data["tasks"] if isinstance(data, dict) else data
+
+
+def test_reset_zeroes_attempts_and_clears_runtime_state(tmp_path):
+    path = write_queue(tmp_path)
+    rc = mq.main(["reset", "--queue", str(path)])
+    assert rc == 0
+    tasks = read_tasks(path)
+    assert [t["attempts"] for t in tasks] == [0, 0, 0]
+    assert [t["status"] for t in tasks] == ["pending", "pending", "pending"]
+    failed = tasks[0]
+    assert "error" not in failed and "startedAt" not in failed and "finishedAt" not in failed
+    # Authored fields survive.
+    assert failed["prompt"] == "do the thing"
+    assert failed["maxAttempts"] == 2
+
+
+def test_reset_attempts_only_leaves_status_and_error(tmp_path):
+    path = write_queue(tmp_path)
+    rc = mq.main(["reset", "--queue", str(path), "--attempts-only"])
+    assert rc == 0
+    failed = read_tasks(path)[0]
+    assert failed["attempts"] == 0
+    assert failed["status"] == "failed"
+    assert failed["error"] == "timed out"
+
+
+def test_reset_status_filter(tmp_path):
+    path = write_queue(tmp_path)
+    rc = mq.main(["reset", "--queue", str(path), "--status", "failed"])
+    assert rc == 0
+    tasks = read_tasks(path)
+    assert tasks[0]["status"] == "pending" and tasks[0]["attempts"] == 0
+    # The done task is untouched.
+    assert tasks[1]["status"] == "done" and tasks[1]["attempts"] == 1
+
+
+def test_reset_dry_run_writes_nothing(tmp_path):
+    path = write_queue(tmp_path)
+    before = path.read_text()
+    rc = mq.main(["reset", "--queue", str(path), "--dry-run"])
+    assert rc == 0
+    assert path.read_text() == before
+    assert not (tmp_path / "queue.json.bak").exists()
+
+
+def test_reset_writes_backup_by_default(tmp_path):
+    path = write_queue(tmp_path)
+    mq.main(["reset", "--queue", str(path)])
+    backup = tmp_path / "queue.json.bak"
+    assert backup.exists()
+    assert read_tasks(backup)[0]["attempts"] == 2
+
+
+def test_reset_no_backup_flag(tmp_path):
+    path = write_queue(tmp_path)
+    mq.main(["reset", "--queue", str(path), "--no-backup"])
+    assert not (tmp_path / "queue.json.bak").exists()
+
+
+def test_clear_requires_yes(tmp_path):
+    path = write_queue(tmp_path)
+    before = path.read_text()
+    rc = mq.main(["clear", "--queue", str(path)])
+    assert rc == 1
+    assert path.read_text() == before
+
+
+def test_clear_deletes_all_tasks(tmp_path):
+    path = write_queue(tmp_path)
+    rc = mq.main(["clear", "--queue", str(path), "--yes"])
+    assert rc == 0
+    assert json.loads(path.read_text()) == {"tasks": []}
+    # The pre-clear queue is recoverable.
+    assert len(read_tasks(tmp_path / "queue.json.bak")) == 3
+
+
+def test_clear_on_empty_queue_is_a_noop(tmp_path):
+    path = write_queue(tmp_path, {"tasks": []})
+    rc = mq.main(["clear", "--queue", str(path), "--yes"])
+    assert rc == 0
+    assert not (tmp_path / "queue.json.bak").exists()
+
+
+def test_bare_array_shape_is_preserved(tmp_path):
+    path = write_queue(tmp_path, QUEUE["tasks"])
+    assert mq.main(["reset", "--queue", str(path)]) == 0
+    assert isinstance(json.loads(path.read_text()), list)
+    assert mq.main(["clear", "--queue", str(path), "--yes"]) == 0
+    assert json.loads(path.read_text()) == []
+
+
+def test_missing_file_errors(tmp_path):
+    try:
+        mq.main(["reset", "--queue", str(tmp_path / "nope.json")])
+    except SystemExit as exc:
+        assert "not found" in str(exc)
+    else:
+        raise AssertionError("expected SystemExit for a missing queue file")
+
+
+def test_non_queue_json_errors(tmp_path):
+    path = tmp_path / "queue.json"
+    path.write_text('{"ok": true}')
+    try:
+        mq.main(["clear", "--queue", str(path), "--yes"])
+    except SystemExit as exc:
+        assert "not a td-barrage queue file" in str(exc)
+    else:
+        raise AssertionError("expected SystemExit for a non-queue file")
+
+
+if __name__ == "__main__":
+    failures = 0
+    for name, fn in sorted(globals().items()):
+        if name.startswith("test_") and callable(fn):
+            try:
+                # crude tmp_path for direct (non-pytest) runs
+                if "tmp_path" in fn.__code__.co_varnames[: fn.__code__.co_argcount]:
+                    import tempfile
+
+                    with tempfile.TemporaryDirectory() as d:
+                        fn(Path(d))
+                else:
+                    fn()
+                print(f"ok   {name}")
+            except AssertionError as exc:
+                failures += 1
+                print(f"FAIL {name}: {exc}")
+    sys.exit(1 if failures else 0)

package/skills/barrage/tests/test_queue_paths.py

@@ -0,0 +1,97 @@
+"""Tests for queue_paths.py — the shared `.agents` queue location rule.
+
+Run: python3 -m pytest .agents/skills/barrage/tests/  (or just `python3 test_queue_paths.py`).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+_SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "queue_paths.py"
+_spec = importlib.util.spec_from_file_location("queue_paths", _SCRIPT)
+assert _spec and _spec.loader
+qp = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(qp)
+
+
+def install(root: Path, agent_root: str, name: str = "barrage") -> Path:
+    """Create <root>/<agent_root>/skills/<name>/ and return it."""
+    skill_dir = root / agent_root / "skills" / name
+    skill_dir.mkdir(parents=True)
+    return skill_dir
+
+
+def test_claude_copy_points_at_the_agents_copy(tmp_path: Path):
+    claude = install(tmp_path, ".claude")
+    agents = install(tmp_path, ".agents")
+
+    assert qp.resolve_queue_path(claude) == agents / "queue.json"
+
+
+def test_agents_copy_uses_itself(tmp_path: Path):
+    install(tmp_path, ".claude")
+    agents = install(tmp_path, ".agents")
+
+    assert qp.resolve_queue_path(agents) == agents / "queue.json"
+
+
+def test_any_agent_root_redirects(tmp_path: Path):
+    codex = install(tmp_path, ".codex")
+    agents = install(tmp_path, ".agents")
+
+    assert qp.resolve_queue_path(codex) == agents / "queue.json"
+
+
+def test_falls_back_when_there_is_no_agents_install(tmp_path: Path):
+    claude = install(tmp_path, ".claude")
+
+    assert qp.resolve_queue_path(claude) == claude / "queue.json"
+
+
+def test_source_checkout_keeps_its_own_queue(tmp_path: Path):
+    """A non-dot root is the toolkit checkout, not an install — never redirect."""
+    checkout = install(tmp_path, "AgentToolkit")
+    install(tmp_path, ".agents")
+
+    assert qp.resolve_queue_path(checkout) == checkout / "queue.json"
+
+
+def test_unfamiliar_layout_keeps_its_own_queue(tmp_path: Path):
+    loose = tmp_path / ".claude" / "barrage"
+    loose.mkdir(parents=True)
+    install(tmp_path, ".agents")
+
+    assert qp.resolve_queue_path(loose) == loose / "queue.json"
+
+
+def test_redirect_target_need_not_exist_yet(tmp_path: Path):
+    """`.agents` exists but this skill is not installed there yet — still canonical."""
+    claude = install(tmp_path, ".claude")
+    (tmp_path / ".agents").mkdir()
+
+    assert qp.resolve_queue_path(claude) == tmp_path / ".agents" / "skills" / "barrage" / "queue.json"
+
+
+def test_custom_filename(tmp_path: Path):
+    claude = install(tmp_path, ".claude")
+    agents = install(tmp_path, ".agents")
+
+    assert qp.resolve_queue_path(claude, "queue.bak.json") == agents / "queue.bak.json"
+
+
+if __name__ == "__main__":
+    failures = 0
+    for name, fn in sorted(globals().items()):
+        if name.startswith("test_") and callable(fn):
+            try:
+                import tempfile
+
+                with tempfile.TemporaryDirectory() as d:
+                    fn(Path(d))
+                print(f"ok   {name}")
+            except AssertionError as exc:
+                failures += 1
+                print(f"FAIL {name}: {exc}")
+    sys.exit(1 if failures else 0)