@caddis/cli 0.4.70 → 0.4.72

package/bundles/antigravity-plugin/scripts/caddis_upstream_check.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""caddis_upstream_check - say when an upstream skill that caddis borrowed ideas from has changed.
+
+Why: /caddis:feature-plan and /caddis:implement adapt ideas from obra/superpowers (writing-plans 7.0.0,
+subagent-driven-development 7.0.0, MIT). `.github/upstream-sources.json` records, per borrowed file, the
+upstream version and the sha256 of the file we read. This script compares that record with the copies
+installed in the Claude Code plugin cache (`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/<path>`),
+so caddis does not fall behind upstream without anyone seeing it. /caddis:usage-review runs it.
+
+One line per source:
+    UP-TO-DATE <id> <version>
+    DRIFT <id> recorded <v> installed <v'> (sha differs): review the upstream diff and port what fits, ...
+    NOT-INSTALLED <id>
+`NO-SOURCES <path>` means there is no record (any repo other than the caddis source repo).
+
+Advisory only: the exit code is always 0. Stdlib only.
+
+Usage:
+    python caddis_upstream_check.py [--sources <json>] [--cache-root <dir>] [--json]
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+SOURCES_REL = Path(".github") / "upstream-sources.json"
+DRIFT_ADVICE = "review the upstream diff and port what fits, then update .github/upstream-sources.json"
+
+
+def default_sources() -> Path:
+    """The record in the current repo; else the one next to this script in a source checkout."""
+    here = Path.cwd() / SOURCES_REL
+    if here.is_file():
+        return here
+    return Path(__file__).resolve().parents[1] / SOURCES_REL
+
+
+def default_cache_root() -> Path:
+    return Path.home() / ".claude" / "plugins" / "cache"
+
+
+def _version_key(version: str) -> tuple:
+    """Numeric parts compare as numbers (7.10.0 > 7.9.0); a non-numeric part sorts before any number."""
+    return tuple((1, int(p)) if p.isdigit() else (0, p) for p in version.split("."))
+
+
+def _sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def installed_copies(cache_root: Path, plugin: str, rel_path: str) -> list[tuple[str, Path]]:
+    """(version, file) for every installed copy, newest version last."""
+    if not cache_root.is_dir():
+        return []
+    found = [(f.parents[len(Path(rel_path).parts) - 1].name, f)
+             for f in cache_root.glob(f"*/{plugin}/*/{rel_path}") if f.is_file()]
+    return sorted(found, key=lambda vf: _version_key(vf[0]))
+
+
+def check_source(src: dict, cache_root: Path) -> dict:
+    sid, recorded = src["id"], src["version"]
+    plugin = sid.split(":", 1)[0]
+    copies = installed_copies(cache_root, plugin, src["path"])
+    row = {"id": sid, "status": "NOT-INSTALLED", "recorded_version": recorded, "installed_version": None,
+           "line": f"NOT-INSTALLED {sid}"}
+    if not copies:
+        return row
+    version, newest = copies[-1]
+    row["installed_version"] = version
+    if _sha256(newest) == src["sha256"]:
+        row.update(status="UP-TO-DATE", line=f"UP-TO-DATE {sid} {recorded}")
+    else:
+        row.update(status="DRIFT",
+                   line=f"DRIFT {sid} recorded {recorded} installed {version} (sha differs): {DRIFT_ADVICE}")
+    return row
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Compare borrowed upstream skills with the installed copies.")
+    ap.add_argument("--sources", type=Path, default=None, help="path to upstream-sources.json")
+    ap.add_argument("--cache-root", type=Path, default=None, help="the Claude Code plugin cache folder")
+    ap.add_argument("--json", action="store_true", help="print the rows as a JSON list")
+    args = ap.parse_args(argv)
+    sources = args.sources or default_sources()
+    cache_root = args.cache_root or default_cache_root()
+    if not sources.is_file():
+        print(f"NO-SOURCES {sources}")
+        return 0
+    try:
+        data = json.loads(sources.read_text(encoding="utf-8"))
+        rows = [check_source(src, cache_root) for src in data.get("sources", [])]
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        print(f"NO-SOURCES {sources} (unreadable: {exc})")
+        return 0
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        for row in rows:
+            print(row["line"])
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bundles/antigravity-plugin/scripts/schemas/coordinator.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "caddis hub coordinator state (coordinator.json)",
+  "description": "One file per repo id, written only by caddis_coordinate.py. Readers accept schema N and N-1.",
+  "type": "object",
+  "required": ["schema", "repo", "coordinator_session", "heartbeat_at", "queue", "merging_now", "deploy_checks",
+               "ledger", "processed_requests"],
+  "properties": {
+    "schema": {"type": "integer", "enum": [0, 1]},
+    "repo": {"type": "string", "minLength": 1},
+    "coordinator_session": {
+      "type": "object",
+      "required": ["name", "sessionId", "pid"],
+      "properties": {
+        "name": {"type": ["string", "null"]},
+        "sessionId": {"type": ["string", "null"]},
+        "pid": {"type": ["integer", "null"]}
+      }
+    },
+    "heartbeat_at": {"$ref": "#/$defs/utc"},
+    "queue": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["pr", "head_sha", "title", "state", "why_waiting", "waits_on", "hotfix", "held",
+                     "entered_ready_at"],
+        "properties": {
+          "pr": {"type": "integer", "minimum": 1},
+          "head_sha": {"type": "string"},
+          "title": {"type": "string"},
+          "state": {"enum": ["waiting", "ci", "ready", "merging", "blocked", "held"]},
+          "why_waiting": {"type": "string"},
+          "waits_on": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["repo", "pr"],
+              "properties": {"repo": {"type": "string"}, "pr": {"type": "integer"}}
+            }
+          },
+          "hotfix": {"type": "boolean"},
+          "held": {"type": "boolean"},
+          "entered_ready_at": {"anyOf": [{"$ref": "#/$defs/utc"}, {"type": "null"}]}
+        }
+      }
+    },
+    "merging_now": {"type": ["integer", "object", "null"]},
+    "deploy_checks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["pr", "merge_sha", "deploy_run", "health", "at"],
+        "properties": {
+          "pr": {"type": "integer"},
+          "merge_sha": {"type": "string", "pattern": "^[0-9a-f]{40}$", "description": "lower-cased"},
+          "deploy_run": {"type": ["integer", "null"]},
+          "health": {"enum": ["pending", "ok", "failed"]},
+          "at": {"$ref": "#/$defs/utc"}
+        }
+      }
+    },
+    "ledger": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["what", "decision", "approved_by", "reason", "window", "request_id", "at"],
+        "properties": {
+          "what": {"type": "string", "minLength": 1},
+          "decision": {"enum": ["approve", "decline"]},
+          "approved_by": {"enum": ["owner", "coordinator"]},
+          "reason": {"type": "string", "minLength": 1},
+          "window": {"type": ["string", "null"], "description": "the session window the decision was made in; \"hub\" for an owner click"},
+          "request_id": {"type": ["string", "null"], "description": "the owner request id; null when not from a request"},
+          "at": {"$ref": "#/$defs/utc"}
+        }
+      }
+    },
+    "processed_requests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "result", "reason", "at"],
+        "properties": {
+          "id": {"type": "string"},
+          "result": {"enum": ["done", "rejected", "expired"]},
+          "reason": {"type": "string"},
+          "at": {"$ref": "#/$defs/utc"}
+        }
+      }
+    }
+  },
+  "$defs": {
+    "utc": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"}
+  }
+}

package/bundles/antigravity-plugin/scripts/schemas/request.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "caddis hub owner request (one line of requests.jsonl)",
+  "description": "Appended by the hub, applied by caddis_coordinate.py intake. Readers accept v N and N-1. pr may be null only for approve/decline, and then args.what is required (ruling R2).",
+  "type": "object",
+  "required": ["v", "id", "created_at", "expires_at", "repo", "pr", "head_sha", "action", "args"],
+  "additionalProperties": false,
+  "properties": {
+    "v": {"type": "integer", "enum": [0, 1]},
+    "id": {"type": "string", "minLength": 1},
+    "created_at": {"$ref": "#/$defs/utc"},
+    "expires_at": {"$ref": "#/$defs/utc"},
+    "repo": {"type": "string", "minLength": 1},
+    "pr": {"type": ["integer", "null"], "minimum": 1},
+    "head_sha": {"type": ["string", "null"], "description": "40 hex characters when pr is set; compared case-insensitively"},
+    "action": {"enum": ["hotfix", "unhotfix", "hold", "release", "approve", "decline"]},
+    "args": {
+      "type": "object",
+      "properties": {"what": {"type": "string", "minLength": 1}}
+    }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"pr": {"type": "null"}}, "required": ["pr"]},
+      "then": {
+        "properties": {
+          "action": {"enum": ["approve", "decline"]},
+          "args": {"required": ["what"]}
+        }
+      },
+      "else": {
+        "properties": {"head_sha": {"type": "string", "pattern": "^[0-9a-fA-F]{40}$"}}
+      }
+    }
+  ],
+  "$defs": {
+    "utc": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"}
+  }
+}

package/bundles/antigravity-plugin/scripts/templates/coordinator.md

@@ -0,0 +1,91 @@
+# Coordinator config
+
+This file is the per-repo config for `/caddis:coordinate`. The coordinator session reads the ONE fenced
+`json` block below. The prose around it is for people.
+
+How to fill it:
+
+- Replace every `"<fill: ...>"` string with the real value. The coordinator refuses to start while any
+  `<fill:` string is left (`caddis_coordinate.py config show` lists them).
+- Keep every key. A missing key also stops the coordinator.
+- Put no host names and no secrets here. The production base URL comes from the environment variable that
+  `deploy.base_url_env` names.
+
+What the keys mean:
+
+| Key | Meaning |
+|---|---|
+| `schema` | The config format version. Keep `1`. |
+| `default_branch` | The branch that PRs merge into. |
+| `merge_method` | `squash`, `merge` or `rebase`. Match the repo's branch protection (linear history needs `squash` or `rebase`). |
+| `required_checks` | The required status checks, as branch protection names them. A fallback only: the coordinator reads branch protection first and tells the owner on a mismatch. |
+| `not_required` | Checks that may fail or skip on a PR without blocking the merge. |
+| `docs_only.signal` | The CI job that decides if a change is docs-only (the other required checks then conclude `skipped`). |
+| `docs_only.deploy_check` | The deploy checks for a docs-only merge. A docs-only push deploys nothing. |
+| `main_workflow` | The name of the CI workflow that runs on the default branch. No merge while it runs. |
+| `reviews.count` | How many reviews a PR needs before it is ready. |
+| `reviews.stop_on` | Which review findings stop a merge. `blocking`: only blocking findings. |
+| `peer_ack.warning_min` | Minutes between the merge warning and the merge. |
+| `peer_ack.ack_file` | Where each peer writes its ack: `{head, acked[], at}`. An ack older than 30 minutes does not count. |
+| `deploy.event` | The event that starts the deploy run (for example `push`). |
+| `deploy.jobs` | The number of jobs in the deploy run. |
+| `deploy.tag` | The release tag scheme. With `calver`, the tag must point at the merge SHA. |
+| `deploy.base_url_env` | The environment variable that holds the production base URL on this machine. |
+| `deploy.auth` | How the checks authenticate to production. |
+| `deploy.version_path` | The JSON endpoint whose `sha` field must equal the merge SHA after the deploy. |
+| `deploy.health_path` | The endpoint that must answer 200 after the deploy. |
+| `deploy.never_health_path` | A path that looks healthy even when the API is dead. Never used as a health check. |
+| `deploy.render_check` | How the PR's session checks a served page: 0 console errors and one value checked against its source. |
+| `deploy.wait` | How to wait for the deploy run. No fixed sleep. |
+| `owner_reserved` | Changes that only the owner may approve. |
+| `stall.busy_silent_min` | Minutes a busy session may stay silent before the coordinator asks. |
+| `stall.ready_no_ready_msg_min` | Minutes a green PR may wait for its session's ready message. |
+| `quiet.coordination` | Quiet hours for merges (`none`: no quiet hours). |
+| `quiet.timing_checks` | When timing checks may run. |
+
+```json
+{
+  "schema": 1,
+  "default_branch": "<fill: the branch that PRs merge into, for example main>",
+  "merge_method": "squash",
+  "required_checks": [
+    "<fill: one required status check as branch protection names it, for example ci / lint_and_test; one string per check>"
+  ],
+  "not_required": [
+    "<fill: one check that may fail or skip on a PR, for example notify; one string per check, or an empty list>"
+  ],
+  "docs_only": {
+    "signal": "<fill: name of the CI job that decides if a change is docs-only>",
+    "deploy_check": ["push_run", "health"]
+  },
+  "main_workflow": "<fill: name of the CI workflow that runs on the default branch>",
+  "reviews": {"count": 2, "stop_on": "blocking"},
+  "peer_ack": {
+    "warning_min": 2,
+    "ack_file": "~/.claude/merge-acks/<repo>/pr-<n>.json"
+  },
+  "deploy": {
+    "event": "push",
+    "jobs": "<fill: number of jobs in the deploy run>",
+    "tag": "<fill: release tag scheme, for example calver, or none>",
+    "base_url_env": "<fill: name of the environment variable that holds the production base URL>",
+    "auth": "<fill: how the checks authenticate to production, for example none>",
+    "version_path": "<fill: path of the JSON endpoint whose sha field is the deployed commit>",
+    "health_path": "<fill: path of the endpoint that must answer 200 after the deploy>",
+    "never_health_path": "<fill: path that looks healthy even when the API is dead, or null>",
+    "render_check": "<fill: how the PR's session checks a served page, for example a headless browser>",
+    "wait": "gh run watch"
+  },
+  "owner_reserved": [
+    "schema change or data write on prod",
+    "permission change",
+    "any open blocking review finding",
+    "<fill: a rule the owner reserved by name; one string per rule, or delete this line>"
+  ],
+  "stall": {"busy_silent_min": 45, "ready_no_ready_msg_min": 20},
+  "quiet": {
+    "coordination": "none",
+    "timing_checks": "<fill: when timing checks may run, for example quiet window only>"
+  }
+}
+```

package/bundles/antigravity-plugin/skills/_registry.md

@@ -58,7 +58,7 @@
 | Office Documents Official | `office-documents-official/` | Hint for Office and PDF file work. Use when the user asks to create, edit, read or convert a Word .docx, PDF, PowerPoint .pptx or Excel .xlsx file. caddis does not ship these skills; points to Anthropic's official document-skills plugin. |
 | Tech Explainer | `tech-explainer/` | >- |
 | Technical Writing | `technical-writing/` | Documentation best practices for READMEs, API docs, architecture docs, runbooks and developer guides. Use when writing or reviewing docs or setting documentation standards. |
-| Writing Plans | `writing-plans/` | Use when you have a spec or requirements for a multi-step task, before touching code |
+| Writing Plans | `writing-plans/` | Use when you have a spec or requirements for a multi-step task, before touching code. In caddis, plans are written with /caddis:feature-plan, the only plan writer; this skill sends you there. |
 
 ### Frontend
 
@@ -80,6 +80,7 @@
 | Add Rules | `add-rules/` | Create canonical rules for ANY folder — write <folder>/AGENTS.md (from the folder template) + a <folder>/CLAUDE.md @import shim. For folders the stack-map generator doesn't cover. |
 | Catchup | `catchup/` | Where were we? A quick list of what this session was doing and what is still open |
 | Cloud Phases | `cloud-phases/` | Run plan phases in Claude Code cloud sessions — write one prompt per phase, push, hand out paste lines, then take the PRs back |
+| Coordinate | `coordinate/` | Run this session as the repo's coordinator — one merge queue for all sessions, one merge at a time, a deploy check after each merge, routine approvals in the ledger. |
 | Decide | `decide/` | Record a decision in one step — .caddis/decisions/<date>-<slug>.md |
 | Digress | `digress/` | Park the current workstream on the stack and switch to a new task — without losing the original |
 | Excalidraw Db | `excalidraw-db/` | Turn a SQL artifact into an Excalidraw diagram for a design review / ARB pack / slide — higher-level, drag-the-boxes format |

package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md

@@ -45,7 +45,7 @@ Start by understanding the current project context, then ask questions one at a
 **Implementation (if continuing):**
 - Ask: "Ready to set up for implementation?"
 - Use the `using-git-worktrees` skill (caddis, devops/) to create an isolated workspace
-- Use `/caddis:feature-plan` for a phased plan, or the `writing-plans` skill (caddis, docs/)
+- Use `/caddis:feature-plan` to write the plan (it is the only plan writer in caddis)
 
 ## Key Principles