@caddis/cli 0.4.92 → 0.4.93

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/README.md +4 -0
  2. package/bundles/antigravity-plugin/agents/debug.md +2 -0
  3. package/bundles/antigravity-plugin/plugin.json +1 -1
  4. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
  5. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
  6. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
  7. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
  8. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
  9. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
  10. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
  11. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
  12. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
  13. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
  14. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
  15. package/bundles/antigravity-plugin/scripts/caddis_checkout_guard.py +1 -1
  16. package/bundles/antigravity-plugin/scripts/caddis_fleet.py +26 -9
  17. package/bundles/antigravity-plugin/scripts/caddis_guide.json +58 -6
  18. package/bundles/antigravity-plugin/scripts/caddis_preload_review.py +554 -0
  19. package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +9 -3
  20. package/bundles/antigravity-plugin/scripts/caddis_run.py +160 -0
  21. package/bundles/antigravity-plugin/scripts/caddis_spawn.py +17 -1
  22. package/bundles/antigravity-plugin/scripts/caddis_upstream_check.py +108 -10
  23. package/bundles/antigravity-plugin/scripts/setup_project_ai.py +65 -1
  24. package/bundles/antigravity-plugin/skills/_registry.md +3 -1
  25. package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md +232 -40
  26. package/bundles/antigravity-plugin/skills/brainstorming/builder-check-prompt.md +25 -0
  27. package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +7 -1
  28. package/bundles/antigravity-plugin/skills/fleet-close/SKILL.md +4 -1
  29. package/bundles/antigravity-plugin/skills/graph-email/SKILL.md +15 -0
  30. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +9 -2
  31. package/bundles/antigravity-plugin/skills/implement/SKILL.md +3 -0
  32. package/bundles/antigravity-plugin/skills/particle-art/SKILL.md +1 -3
  33. package/bundles/antigravity-plugin/skills/preload-review/SKILL.md +69 -0
  34. package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +4 -0
  35. package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md +6 -5
  36. package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md +5 -0
  37. package/bundles/antigravity-plugin/skills/tdd/SKILL.md +2 -1
  38. package/bundles/antigravity-plugin/skills/usage-review/SKILL.md +2 -0
  39. package/bundles/antigravity-plugin-extras/plugin.json +1 -1
  40. package/bundles/antigravity-plugin-extras/skills/_registry.md +1 -0
  41. package/bundles/antigravity-plugin-extras/skills/graph-email/SKILL.md +53 -0
  42. package/bundles/antigravity-plugin-extras/skills/graph-email/email.toml.example +44 -0
  43. package/bundles/antigravity-plugin-extras/skills/graph-email/scripts/send_email.py +432 -0
  44. package/bundles/codex/.codex/skills/media/particle-art/SKILL.md +1 -3
  45. package/bundles/codex/.codex/skills/workflow/brainstorming/SKILL.md +232 -40
  46. package/bundles/codex/.codex/skills/workflow/brainstorming/builder-check-prompt.md +25 -0
  47. package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +4 -0
  48. package/bundles/codex/.codex/skills/workflow/roadmap/assets/plan-resume-prompt.md +6 -5
  49. package/bundles/manifest.json +3 -3
  50. package/dist/export/assets/export-CMtV-slT.css +1 -0
  51. package/dist/export/index.html +2 -2
  52. package/dist/ui/assets/{Activity-DZKPMOeV.js → Activity-BDjet2xd.js} +1 -1
  53. package/dist/ui/assets/Guide-Czn5sK0f.js +9 -0
  54. package/dist/ui/assets/Guide-D-Zy4cUT.css +1 -0
  55. package/dist/ui/assets/{RoadmapTab-DPsiSmIF.js → RoadmapTab-Bd8geyQx.js} +1 -1
  56. package/dist/ui/assets/index-Bd0Z4jR8.css +1 -0
  57. package/dist/ui/assets/{index-xl156OCN.js → index-CmngQ8Mk.js} +12 -12
  58. package/dist/ui/index.html +2 -2
  59. package/package.json +1 -1
  60. package/dist/export/assets/export-HxTgj3z2.css +0 -1
  61. package/dist/ui/assets/Guide-5ZFfL6sl.js +0 -9
  62. package/dist/ui/assets/Guide-Dnsb-TRd.css +0 -1
  63. package/dist/ui/assets/index-DGlNAmeA.css +0 -1
  64. /package/dist/export/assets/{export-B7BBDg5I.js → export-DtlDFN4L.js} +0 -0
@@ -0,0 +1,160 @@
1
+ #!/usr/bin/env python3
2
+ """caddis_run.py: run a caddis script by its bare name, from the plugin that is installed NOW.
3
+
4
+ Usage: python "<home>/.caddis/bin/caddis_run.py" <script.py> [args...]
5
+
6
+ Why it exists: Claude Code expands `${CLAUDE_PLUGIN_ROOT}` to a folder with the plugin version in its name
7
+ (`~/.claude/plugins/cache/caddis/caddis/1.3.165/`). A restart prompt, relay or restart sheet that copies that
8
+ expanded path fails after the next update, because the old version folder is gone. Text that a LATER session reads
9
+ names this launcher instead. The SessionStart hook keeps the copy in `~/.caddis/bin/` fresh (`install_launcher`).
10
+
11
+ The launcher finds the install in `~/.claude/plugins/installed_plugins.json` (key `caddis@caddis`), else the highest
12
+ version folder under `~/.claude/plugins/cache/caddis/caddis/`. It runs `<install>/scripts/<script.py>` with the
13
+ same Python, and passes stdout, stderr and the exit code through.
14
+
15
+ Exit codes: the script's own; 2 = bad usage or a script name that is not a bare `.py` file name; 3 = no caddis
16
+ install found, or the script is not in it.
17
+
18
+ Standard library only. This file is copied alone to `~/.caddis/bin/`: it imports no sibling script.
19
+ """
20
+ from __future__ import annotations
21
+
22
+ import json
23
+ import os
24
+ import re
25
+ import subprocess
26
+ import sys
27
+ import tempfile
28
+ from pathlib import Path
29
+
30
+ EXIT_USAGE, EXIT_NOT_FOUND = 2, 3
31
+ PLUGIN_KEY = "caddis@caddis"
32
+ LAUNCHER_NAME = "caddis_run.py"
33
+
34
+ # A path into the versioned plugin cache: `.../plugins/cache/caddis/caddis/1.3.165/...`. Gone after the next update.
35
+ VERSIONED_PATH = re.compile(r"[/\\]caddis[/\\]caddis[/\\]\d")
36
+ VERSIONED_PATH_HELP = ("it names a versioned plugin path (.../caddis/caddis/<version>/...), which breaks at the next "
37
+ f'update: write python "<home>/.caddis/bin/{LAUNCHER_NAME}" <script> ... instead')
38
+
39
+ _BARE_PY = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.-]*\.py")
40
+ _VERSION = re.compile(r"\d+(\.\d+)*")
41
+
42
+
43
+ def valid_script_name(name: str) -> bool:
44
+ """A bare file name ending `.py`: no folder part, no `..`, no drive, no space."""
45
+ return bool(_BARE_PY.fullmatch(name)) and ".." not in name
46
+
47
+
48
+ def _install_paths(home: Path) -> list[Path]:
49
+ """The `installPath` values of `caddis@caddis` in installed_plugins.json: a list of entries or one object."""
50
+ try:
51
+ data = json.loads((home / ".claude" / "plugins" / "installed_plugins.json").read_text(encoding="utf-8"))
52
+ except (OSError, ValueError):
53
+ return []
54
+ if not isinstance(data, dict):
55
+ return []
56
+ plugins = data.get("plugins", data)
57
+ entry = plugins.get(PLUGIN_KEY) if isinstance(plugins, dict) else None
58
+ entries = entry if isinstance(entry, list) else [entry]
59
+ return [Path(e["installPath"]) for e in entries if isinstance(e, dict) and isinstance(e.get("installPath"), str)]
60
+
61
+
62
+ def _cache_dir(home: Path) -> Path:
63
+ return home / ".claude" / "plugins" / "cache" / "caddis" / "caddis"
64
+
65
+
66
+ def _newest_cached(home: Path) -> Path | None:
67
+ """The version folder with the highest version, compared as tuples of ints (1.3.99 < 1.3.172)."""
68
+ try:
69
+ found = [(tuple(int(p) for p in d.name.split(".")), d) for d in _cache_dir(home).iterdir()
70
+ if d.is_dir() and _VERSION.fullmatch(d.name) and (d / "scripts").is_dir()]
71
+ except OSError:
72
+ return None
73
+ return max(found, key=lambda pair: pair[0])[1] if found else None
74
+
75
+
76
+ def find_install(home: Path) -> Path | None:
77
+ """The installed caddis plugin folder, or None."""
78
+ for path in _install_paths(home):
79
+ if (path / "scripts").is_dir():
80
+ return path
81
+ return _newest_cached(home)
82
+
83
+
84
+ def main(argv: list[str], home: Path | None = None) -> int:
85
+ home = home or Path.home()
86
+ if not argv:
87
+ sys.stderr.write(f'usage: python "<home>/.caddis/bin/{LAUNCHER_NAME}" <script.py> [args...]\n')
88
+ return EXIT_USAGE
89
+ name, rest = argv[0], argv[1:]
90
+ if not valid_script_name(name):
91
+ sys.stderr.write(f"{LAUNCHER_NAME}: the script must be a bare file name that ends .py (no folder, no ..): {name!r}\n")
92
+ return EXIT_USAGE
93
+ install = find_install(home)
94
+ if install is None:
95
+ sys.stderr.write(f"{LAUNCHER_NAME}: no caddis plugin found: looked for key {PLUGIN_KEY} in "
96
+ f"{home / '.claude' / 'plugins' / 'installed_plugins.json'} and for a version folder in "
97
+ f"{_cache_dir(home)}\n")
98
+ return EXIT_NOT_FOUND
99
+ script = install / "scripts" / name
100
+ if not script.is_file():
101
+ sys.stderr.write(f"{LAUNCHER_NAME}: {name} is not in {install / 'scripts'}\n")
102
+ return EXIT_NOT_FOUND
103
+ return subprocess.call([sys.executable, str(script), *rest])
104
+
105
+
106
+ # -- the stable text, and the copy that keeps the launcher fresh -------------------------------------------------------
107
+
108
+
109
+ def _base(home: Path | None) -> Path:
110
+ """`~` for the launcher copy: the `home` argument beats CADDIS_HOME, which beats the user's home folder
111
+ (the rule of caddis_created.py and setup_project_ai.py: a test or sandbox points CADDIS_HOME at a temp folder)."""
112
+ return Path(home) if home else Path(os.environ.get("CADDIS_HOME") or Path.home())
113
+
114
+
115
+ def launcher_path(home: Path | None = None) -> Path:
116
+ return _base(home) / ".caddis" / "bin" / LAUNCHER_NAME
117
+
118
+
119
+ def stable_prefix(home: Path | None = None) -> str:
120
+ """`python "<home>/.caddis/bin/caddis_run.py"`: put a bare script name and its arguments after it."""
121
+ return f'python "{launcher_path(home).as_posix()}"'
122
+
123
+
124
+ def stable_command(script: str, home: Path | None = None) -> str:
125
+ """`python "<home>/.caddis/bin/caddis_run.py" <script>`: the form for TEXT THAT A LATER SESSION READS.
126
+ Forward slashes, so the same text works in bash and PowerShell. Machine-local on purpose."""
127
+ if not valid_script_name(script):
128
+ raise ValueError(f"not a bare .py file name: {script!r}")
129
+ return f"{stable_prefix(home)} {script}"
130
+
131
+
132
+ def install_launcher(src: str | os.PathLike, home: Path | None = None) -> bool:
133
+ """Copy `src` to `~/.caddis/bin/caddis_run.py` when the content differs. True when it wrote.
134
+
135
+ A temp file in the same folder, then os.replace: a reader never sees a half-written launcher. Raises on error;
136
+ the SessionStart hook catches it, because a launcher that cannot be refreshed must never stop a session."""
137
+ data = Path(src).read_bytes()
138
+ dest = launcher_path(home)
139
+ try:
140
+ if dest.read_bytes() == data:
141
+ return False
142
+ except OSError:
143
+ pass
144
+ dest.parent.mkdir(parents=True, exist_ok=True)
145
+ fd, tmp = tempfile.mkstemp(dir=dest.parent, prefix=".caddis_run-", suffix=".tmp")
146
+ try:
147
+ with os.fdopen(fd, "wb") as fh:
148
+ fh.write(data)
149
+ os.replace(tmp, dest)
150
+ except BaseException:
151
+ try:
152
+ os.unlink(tmp)
153
+ except OSError:
154
+ pass
155
+ raise
156
+ return True
157
+
158
+
159
+ if __name__ == "__main__":
160
+ sys.exit(main(sys.argv[1:]))
@@ -39,6 +39,14 @@ import time
39
39
  from dataclasses import dataclass, field
40
40
  from pathlib import Path
41
41
 
42
+ try:
43
+ import caddis_run # VERSIONED_PATH: a handover never names a versioned plugin path
44
+ except ModuleNotFoundError as _exc:
45
+ if _exc.name != "caddis_run":
46
+ raise
47
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
48
+ import caddis_run
49
+
42
50
  if hasattr(sys.stdout, "reconfigure"):
43
51
  sys.stdout.reconfigure(encoding="utf-8", errors="replace")
44
52
 
@@ -110,9 +118,13 @@ class DocFindings:
110
118
  # different. A stale hash is an accident the successor will notice; a stored answer key
111
119
  # defeats the exercise SILENTLY — it certifies a reader who understood nothing.
112
120
  answer_key: list[tuple[int, str]] = field(default_factory=list)
121
+ # A path into the versioned plugin cache. The successor reads the handover after an update, when that
122
+ # folder is gone: the command fails with "can't open file". Refusing, so the author fixes it now.
123
+ versioned_paths: list[tuple[int, str]] = field(default_factory=list)
113
124
 
114
125
  def ok(self) -> bool:
115
- return not self.stale_prone and not self.missing_paths and not self.answer_key
126
+ return (not self.stale_prone and not self.missing_paths and not self.answer_key
127
+ and not self.versioned_paths)
116
128
 
117
129
 
118
130
  # ── answer-key detection ────────────────────────────────────────────────────────────────────
@@ -184,6 +196,8 @@ def check_document(text: str, repo_root: Path | None = None) -> DocFindings:
184
196
  if _INLINE_ANSWER.search(line):
185
197
  out.answer_key.append((n, "a question and its answer on one line. The questions may "
186
198
  "ship; the answers may not"))
199
+ if caddis_run.VERSIONED_PATH.search(line): # a fence does not exempt it: a command in a fence is the case
200
+ out.versioned_paths.append((n, caddis_run.VERSIONED_PATH_HELP))
187
201
  if _is_exempt(line, in_fence):
188
202
  continue
189
203
  for m in _HASH.finditer(line):
@@ -915,6 +929,8 @@ def main(argv: list[str] | None = None) -> int:
915
929
  sys.stderr.write(f"[spawn] {doc.name} FAILS round 0:\n")
916
930
  for n, msg in f.answer_key:
917
931
  sys.stderr.write(f" line {n}: ANSWER KEY — {msg}" + chr(10))
932
+ for n, msg in f.versioned_paths:
933
+ sys.stderr.write(f" line {n}: {msg}\n")
918
934
  for n, msg in f.stale_prone:
919
935
  sys.stderr.write(f" line {n}: {msg}\n")
920
936
  for p_ in f.missing_paths:
@@ -1,33 +1,55 @@
1
1
  #!/usr/bin/env python3
2
2
  """caddis_upstream_check - say when an upstream skill that caddis borrowed ideas from has changed.
3
3
 
4
- Why: /caddis:feature-plan and /caddis:implement adapt ideas from obra/superpowers (writing-plans 7.0.0,
5
- subagent-driven-development 7.0.0, MIT). `.github/upstream-sources.json` records, per borrowed file, the
6
- upstream version and the sha256 of the file we read. This script compares that record with the copies
7
- installed in the Claude Code plugin cache (`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/<path>`),
8
- so caddis does not fall behind upstream without anyone seeing it. /caddis:usage-review runs it.
4
+ Why: caddis owns the routing-critical skills and commands that it adapted from obra/superpowers
5
+ (writing-plans, subagent-driven-development, brainstorming, using-git-worktrees; MIT). The other superpowers
6
+ skills are used straight from the plugin. `.github/upstream-sources.json` records, per borrowed file, the upstream version and the
7
+ sha256 of the file we read. This script compares that record with upstream, so caddis does not fall
8
+ behind without anyone seeing it. /caddis:usage-review runs the local mode. The weekly workflow
9
+ `.github/workflows/upstream-drift.yml` runs `--remote` and opens one issue when anything drifts.
10
+
11
+ Two modes:
12
+ local (default) compare with the copies installed in the Claude Code plugin cache
13
+ (`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/<path>`). It is blind
14
+ when the upstream plugin is turned off or not installed.
15
+ --remote ask GitHub instead: take the latest release tag of each `upstream` repo (the
16
+ newest tag when there is no release), fetch the file at that tag from
17
+ raw.githubusercontent.com and hash it. Needs the network. Set GITHUB_TOKEN to
18
+ avoid the anonymous API rate limit. Stdlib `urllib` only.
9
19
 
10
20
  One line per source:
11
21
  UP-TO-DATE <id> <version>
12
- DRIFT <id> recorded <v> installed <v'> (sha differs): review the upstream diff and port what fits, ...
13
- NOT-INSTALLED <id>
22
+ DRIFT <id> recorded <v> installed <new> (sha differs): review the upstream diff and port what fits, ...
23
+ DRIFT <id> recorded <v> upstream <tag> (sha differs): ... (--remote)
24
+ DRIFT <id> recorded <v> upstream <tag> (file not found at that tag): ... (--remote)
25
+ NOT-INSTALLED <id> (local only)
26
+ UNREACHABLE <id> <reason> (--remote: network or API error)
14
27
  `NO-SOURCES <path>` means there is no record (any repo other than the caddis source repo).
15
28
 
16
- Advisory only: the exit code is always 0. Stdlib only.
29
+ Advisory: the exit code is 0 unless `--fail-on-drift` is set and some line is DRIFT (then 1).
30
+ This script never copies upstream text. The caddis files are adapted, so a copy would undo the
31
+ adaptation: a human reads the diff and ports what fits.
17
32
 
18
33
  Usage:
19
34
  python caddis_upstream_check.py [--sources <json>] [--cache-root <dir>] [--json]
35
+ [--remote] [--fail-on-drift]
20
36
  """
21
37
  from __future__ import annotations
22
38
 
23
39
  import argparse
24
40
  import hashlib
25
41
  import json
42
+ import os
26
43
  import sys
44
+ import urllib.error
45
+ import urllib.request
27
46
  from pathlib import Path
28
47
 
29
48
  SOURCES_REL = Path(".github") / "upstream-sources.json"
30
49
  DRIFT_ADVICE = "review the upstream diff and port what fits, then update .github/upstream-sources.json"
50
+ API_ROOT = "https://api.github.com"
51
+ RAW_ROOT = "https://raw.githubusercontent.com"
52
+ TIMEOUT_SECONDS = 20
31
53
 
32
54
 
33
55
  def default_sources() -> Path:
@@ -78,11 +100,83 @@ def check_source(src: dict, cache_root: Path) -> dict:
78
100
  return row
79
101
 
80
102
 
103
+ # ---- remote mode ------------------------------------------------------------------------------------
104
+
105
+ class FetchError(Exception):
106
+ """A network or HTTP failure. `status` is the HTTP status code, or None for a network error."""
107
+
108
+ def __init__(self, message: str, status: int | None = None):
109
+ super().__init__(message)
110
+ self.status = status
111
+
112
+
113
+ def fetch(url: str, token: str | None = None) -> bytes:
114
+ """GET a URL and return the body. Raise FetchError on any failure. Tests replace this function."""
115
+ headers = {"User-Agent": "caddis-upstream-check", "Accept": "application/vnd.github+json"}
116
+ if token:
117
+ headers["Authorization"] = f"Bearer {token}"
118
+ try:
119
+ with urllib.request.urlopen(urllib.request.Request(url, headers=headers), timeout=TIMEOUT_SECONDS) as resp:
120
+ return resp.read()
121
+ except urllib.error.HTTPError as exc:
122
+ raise FetchError(f"HTTP {exc.code} for {url}", exc.code) from exc
123
+ except (urllib.error.URLError, OSError, ValueError) as exc:
124
+ raise FetchError(f"{exc} for {url}") from exc
125
+
126
+
127
+ def latest_tag(upstream: str, token: str | None = None) -> str | None:
128
+ """The latest release tag of `owner/repo`; when it has no release, the newest tag; else None."""
129
+ try:
130
+ release = json.loads(fetch(f"{API_ROOT}/repos/{upstream}/releases/latest", token))
131
+ if release.get("tag_name"):
132
+ return str(release["tag_name"])
133
+ except FetchError as exc:
134
+ if exc.status != 404:
135
+ raise
136
+ tags = json.loads(fetch(f"{API_ROOT}/repos/{upstream}/tags?per_page=100", token))
137
+ names = [str(tag["name"]) for tag in tags if isinstance(tag, dict) and tag.get("name")]
138
+ return max(names, key=lambda name: _version_key(name.lstrip("v"))) if names else None
139
+
140
+
141
+ def check_source_remote(src: dict, tags: dict[str, str | None], token: str | None = None) -> dict:
142
+ """Compare one record with the file at the latest upstream tag. `tags` caches one lookup per repo."""
143
+ sid, recorded, upstream = src["id"], src["version"], src["upstream"]
144
+ row = {"id": sid, "status": "UNREACHABLE", "recorded_version": recorded, "installed_version": None,
145
+ "upstream_tag": None, "line": ""}
146
+
147
+ def done(status: str, line: str) -> dict:
148
+ row.update(status=status, line=line)
149
+ return row
150
+
151
+ try:
152
+ if upstream not in tags:
153
+ tags[upstream] = latest_tag(upstream, token)
154
+ tag = tags[upstream]
155
+ if tag is None:
156
+ return done("UNREACHABLE", f"UNREACHABLE {sid} {upstream} has no releases and no tags")
157
+ row["upstream_tag"] = tag
158
+ try:
159
+ body = fetch(f"{RAW_ROOT}/{upstream}/{tag}/{src['path']}", token)
160
+ except FetchError as exc:
161
+ if exc.status == 404:
162
+ return done("DRIFT", f"DRIFT {sid} recorded {recorded} upstream {tag} "
163
+ f"(file not found at that tag): {DRIFT_ADVICE}")
164
+ raise
165
+ except (FetchError, ValueError, KeyError, TypeError) as exc:
166
+ return done("UNREACHABLE", f"UNREACHABLE {sid} {exc}")
167
+ if hashlib.sha256(body).hexdigest() == src["sha256"]:
168
+ return done("UP-TO-DATE", f"UP-TO-DATE {sid} {recorded}")
169
+ return done("DRIFT", f"DRIFT {sid} recorded {recorded} upstream {tag} (sha differs): {DRIFT_ADVICE}")
170
+
171
+
81
172
  def main(argv: list[str] | None = None) -> int:
82
173
  ap = argparse.ArgumentParser(description="Compare borrowed upstream skills with the installed copies.")
83
174
  ap.add_argument("--sources", type=Path, default=None, help="path to upstream-sources.json")
84
175
  ap.add_argument("--cache-root", type=Path, default=None, help="the Claude Code plugin cache folder")
85
176
  ap.add_argument("--json", action="store_true", help="print the rows as a JSON list")
177
+ ap.add_argument("--remote", action="store_true",
178
+ help="ask GitHub for the latest release of each upstream repo instead of reading the plugin cache")
179
+ ap.add_argument("--fail-on-drift", action="store_true", help="exit 1 when any source shows DRIFT")
86
180
  args = ap.parse_args(argv)
87
181
  sources = args.sources or default_sources()
88
182
  cache_root = args.cache_root or default_cache_root()
@@ -91,7 +185,11 @@ def main(argv: list[str] | None = None) -> int:
91
185
  return 0
92
186
  try:
93
187
  data = json.loads(sources.read_text(encoding="utf-8"))
94
- rows = [check_source(src, cache_root) for src in data.get("sources", [])]
188
+ if args.remote:
189
+ token, tags = os.environ.get("GITHUB_TOKEN") or None, {}
190
+ rows = [check_source_remote(src, tags, token) for src in data.get("sources", [])]
191
+ else:
192
+ rows = [check_source(src, cache_root) for src in data.get("sources", [])]
95
193
  except (OSError, ValueError, KeyError, TypeError) as exc:
96
194
  print(f"NO-SOURCES {sources} (unreadable: {exc})")
97
195
  return 0
@@ -100,7 +198,7 @@ def main(argv: list[str] | None = None) -> int:
100
198
  else:
101
199
  for row in rows:
102
200
  print(row["line"])
103
- return 0
201
+ return 1 if args.fail_on_drift and any(row["status"] == "DRIFT" for row in rows) else 0
104
202
 
105
203
 
106
204
  if __name__ == "__main__":
@@ -1201,6 +1201,7 @@ agent-log.jsonl
1201
1201
  usage-log.jsonl.1
1202
1202
  agent-log.jsonl.1
1203
1203
  .last-usage-review
1204
+ .last-preload-review
1204
1205
  relay.md
1205
1206
  relay/
1206
1207
  session-state.md
@@ -1490,6 +1491,68 @@ def ensure_user_env(dry: bool, home: Path | None = None) -> list[str]:
1490
1491
  + ("" if not raw else " (previous version saved as settings.json.caddis-bak)")]
1491
1492
 
1492
1493
 
1494
+ # ── superpowers twins that caddis replaces ──────────────────────────────────────────────────
1495
+ # caddis owns the routing-critical skills: brainstorming, plans (/caddis:feature-plan), running plans
1496
+ # (/caddis:implement) and worktrees. The superpowers plugin ships skills with the same names; its
1497
+ # writing-plans and executing-plans skip the caddis model routing. A deny rule blocks such a skill
1498
+ # ("Skill execution blocked by permission rules") WITHOUT a prompt, so it keeps the zero-prompt setup
1499
+ # (an `ask` rule would prompt every time). Every other superpowers skill is used straight from the plugin.
1500
+ # inject_relay.py re-states this list to warn when a rule is missing; a test keeps the two equal.
1501
+ SUPERPOWERS_DENY = (
1502
+ "Skill(superpowers:brainstorming)",
1503
+ "Skill(superpowers:writing-plans)",
1504
+ "Skill(superpowers:executing-plans)",
1505
+ "Skill(superpowers:subagent-driven-development)",
1506
+ "Skill(superpowers:using-git-worktrees)",
1507
+ )
1508
+
1509
+
1510
+ def ensure_superpowers_deny(dry: bool, home: Path | None = None) -> str:
1511
+ """Add the SUPERPOWERS_DENY rules to the user's `permissions.deny`, additively and idempotently.
1512
+
1513
+ Other deny entries (and every other setting) are never removed or reordered. Same safety rules as
1514
+ ensure_user_env: a file that does not parse is never rewritten, a backup is kept
1515
+ (`settings.json.caddis-deny-bak`, its own name so it cannot overwrite another function's backup), the
1516
+ write is atomic, and `CADDIS_NO_SETTINGS_ENV` skips it. Known limit, as for ensure_user_env: a write by
1517
+ Claude Code between this read and the replace is lost."""
1518
+ if os.environ.get("CADDIS_NO_SETTINGS_ENV"):
1519
+ return "superpowers deny rules: skipped (CADDIS_NO_SETTINGS_ENV set)"
1520
+ path = _user_settings_path(home)
1521
+ if path.is_file():
1522
+ raw = path.read_text(encoding="utf-8", errors="ignore")
1523
+ try:
1524
+ data = json.loads(raw)
1525
+ except json.JSONDecodeError as exc:
1526
+ return (f"superpowers deny rules: {path} is NOT VALID JSON ({exc.msg}, line {exc.lineno}) — "
1527
+ "left untouched; fix it by hand.")
1528
+ if not isinstance(data, dict):
1529
+ return f"superpowers deny rules: {path} is not a JSON object — left untouched"
1530
+ else:
1531
+ raw, data = "", {}
1532
+ perms = data.get("permissions")
1533
+ if perms is None:
1534
+ perms = {}
1535
+ elif not isinstance(perms, dict):
1536
+ return f"superpowers deny rules: {path} has a non-object `permissions` — left untouched"
1537
+ deny = perms.get("deny")
1538
+ if deny is None:
1539
+ deny = []
1540
+ elif not isinstance(deny, list):
1541
+ return f"superpowers deny rules: {path} has a non-list `permissions.deny` — left untouched"
1542
+ missing = [rule for rule in SUPERPOWERS_DENY if rule not in deny]
1543
+ if not missing:
1544
+ return f"superpowers deny rules: all {len(SUPERPOWERS_DENY)} already in {path}"
1545
+ perms["deny"] = deny + missing
1546
+ data["permissions"] = perms
1547
+ if not dry:
1548
+ path.parent.mkdir(parents=True, exist_ok=True)
1549
+ if raw:
1550
+ path.with_suffix(".json.caddis-deny-bak").write_text(raw, encoding="utf-8")
1551
+ _atomic_write_json(path, data)
1552
+ verb = "would add" if dry else "added"
1553
+ return f"superpowers deny rules: {verb} {len(missing)} to permissions.deny in {path}"
1554
+
1555
+
1493
1556
  CLEANUP_PERIOD_KEY = "cleanupPeriodDays"
1494
1557
  CLEANUP_PERIOD_DAYS = 120
1495
1558
 
@@ -1534,7 +1597,7 @@ def scaffold_artifact_dir(target: Path, dry: bool) -> list[str]:
1534
1597
  """Create the harness-owned .caddis/ artifact tree + a default .gitignore + a config example.
1535
1598
 
1536
1599
  Committed subdirs: plans, handoffs, agent-docs, prd, kb, prompts, comms. Transient state
1537
- (reviews/*.html, usage-log.jsonl, .last-usage-review, relay*, session-state.md,
1600
+ (reviews/*.html, usage-log.jsonl, .last-usage-review, .last-preload-review, relay*, session-state.md,
1538
1601
  PROJECT-FACTS.md) is gitignored. .caddis/ is the default home for every working-artifact kind (Track A
1539
1602
  Phase A3) — kb/ and prompts/ round out plans/prd/agent-docs/reviews so nothing has to
1540
1603
  scatter to the repo root or .github/. Also drops a documented `config.toml.example`
@@ -1832,6 +1895,7 @@ def main() -> int:
1832
1895
  for line in ensure_user_env(args.dry_run):
1833
1896
  print(f" {line}")
1834
1897
  print(f" {ensure_cleanup_period(args.dry_run)}")
1898
+ print(f" {ensure_superpowers_deny(args.dry_run)}")
1835
1899
 
1836
1900
  print("-- doc-coverage discipline (DOC-MAP + page guide + checker)")
1837
1901
  for line in emit_doc_discipline(target, ident, args.force, args.dry_run):
@@ -40,6 +40,7 @@
40
40
  | Ci Cd Pipeline | `ci-cd-pipeline/` | CI/CD pipelines for GitHub Actions and Azure DevOps: build and deploy workflows, quality gates, environment promotion and release automation. |
41
41
  | Gh Cli | `gh-cli/` | GitHub CLI operations — issues, PRs, releases, and repo management |
42
42
  | Git Commit | `git-commit/` | Create well-structured conventional commit messages following Conventional Commits standard. Use when committing changes, preparing PRs, or generating changelogs. |
43
+ | Graph Email | `graph-email/` | Send a Markdown file as an email through Microsoft Graph or SMTP, as set in ~/.caddis/email.toml. Default recipient is the owner. |
43
44
  | Port To Github | `port-to-github/` | >- |
44
45
  | Safe Cleanup | `safe-cleanup/` | Use BEFORE deleting a directory tree, scratchpad or git worktree, or "tidying up" generated folders, especially on Windows, where deleting through a junction or symlink destroys its target; and to verify a venv or node_modules survived. |
45
46
  | Using Git Worktrees | `using-git-worktrees/` | Use when starting feature work that needs isolation from the current workspace, or before executing an implementation plan: creates an isolated git worktree safely. |
@@ -100,6 +101,7 @@
100
101
  | Park | `park/` | File a future-work item in the one backlog — .caddis/parking-lot/ — or list what is open |
101
102
  | Pr Merge | `pr-merge/` | End-to-end pull request and merge lane — push feature branch, open or update PR, monitor CI to green, merge to default branch, and clean up the feature branch. |
102
103
  | Prd | `prd/` | Capture requirements through structured discovery and write a PRD |
104
+ | Preload Review | `preload-review/` | Show what loads before the first prompt in every repo (rules, memory index, skills, MCP names) and list what to shorten |
103
105
  | Rca | `rca/` | Record a root cause in one step — .caddis/rca/<date>-<slug>.md — or close one with the fixing commit |
104
106
  | Review Pr | `review-pr/` | Review someone else's OPEN pull request end to end — what changed, what CI says, what is risky — then approve or request changes. Never approves on its own. |
105
107
  | Ship | `ship/` | Commit, push, and monitor the deploy pipeline (auto-detects Gitea, GitHub Actions, or local-only) |
@@ -135,7 +137,7 @@
135
137
  | Skill | Path | When to Use |
136
138
  |-------|------|-------------|
137
139
  | Best Practices | `best-practices/` | >- |
138
- | Brainstorming | `brainstorming/` | You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. |
140
+ | Brainstorming | `brainstorming/` | Use before any creative work: new features, components or behavior changes, or planning anything new. Finds what the user wants first. |
139
141
  | Context Curator | `context-curator/` | Compress and prioritize codebase context before handing work to reasoning agents, minimizing token waste while preserving the required decision inputs. |
140
142
  | Preflight | `preflight/` | Plan-vs-codebase validation — verifies API contracts, type names, field accuracy, dependencies, and paths before implementation begins |
141
143
  | Roadmap | `roadmap/` | Track milestones across plans in .caddis/roadmaps/<slug>/: next batch, typed blockers, rollup. Every change is a docs PR via caddis_roadmap.py. |