@caddis/cli 0.4.34 → 0.4.35

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

@@ -42,6 +42,13 @@ import subprocess
 import sys
 from pathlib import Path
 
+# Shared header reader. setup_project_ai copies this checker into a project's scripts/ without
+# it, so fall back to this file's own top-level field reader rather than crashing there.
+try:
+    from caddis_frontmatter import parse as _parse_header
+except ImportError:  # pragma: no cover - exercised by the copied-alone setup test
+    _parse_header = None
+
 # Shared per-repo config reader + artifact-dir resolution (fail-open). Fall back to shims if it's
 # ever absent, so the gate degrades to baked-in defaults rather than crashing.
 try:
@@ -210,6 +217,17 @@ def frontmatter_block(text: str) -> str | None:
     return match.group(1) if match else None
 
 
+def _header_fields(text: str) -> dict:
+    """Top-level header fields: the shared reader when present, else ``type``/``status``/``stale_after``."""
+    if _parse_header is not None:
+        return _parse_header(text)
+    block = frontmatter_block(text)
+    if block is None:
+        return {}
+    fields = ((key, _top_level_field(block, key)) for key in ("type", "status", "stale_after"))
+    return {key: _scalar(field[0]) for key, field in fields if field is not None}
+
+
 def _scalar(raw: str) -> str:
     """A frontmatter scalar with its trailing ``# comment`` and surrounding quotes removed."""
     return re.sub(r"\s+#.*$", "", raw).strip().strip("'\"").strip()
@@ -304,13 +322,10 @@ def misfiled_hub_spawns(root: Path) -> list[str]:
         if rel.startswith(HUB_REPORTS_DIR):
             continue
         try:
-            block = frontmatter_block(f.read_text(encoding="utf-8", errors="ignore"))
+            meta = _header_fields(f.read_text(encoding="utf-8", errors="ignore"))
         except OSError:
             continue
-        if block is None:
-            continue
-        field = _top_level_field(block, "type")
-        if field and _scalar(field[0]).strip().lower() == "hub-spawn":
+        if str(meta.get("type", "")).strip().lower() == "hub-spawn":
             out.append(rel)
     return out
 
@@ -325,11 +340,11 @@ def trust_signal_warnings(text: str) -> list[str]:
     block = frontmatter_block(text)
     if block is None:
         return []
+    meta = _header_fields(text)
     warns: list[str] = []
 
-    status = _top_level_field(block, "status")
-    if status is not None:
-        value = _scalar(status[0])
+    if "status" in meta:
+        value = _scalar(str(meta["status"]))
         # Only a single bare token is vetted. caddis has long-standing docs whose status is a
         # sentence ("DRAFT — approved shape (Option 2), awaiting go"); vetting those would nag
         # about prose that predates the field's vocabulary. A one-word typo still surfaces.
@@ -339,9 +354,8 @@ def trust_signal_warnings(text: str) -> list[str]:
                 f"({', '.join(sorted(TRUST_STATUS_VALUES))})"
             )
 
-    stale = _top_level_field(block, "stale_after")
-    if stale is not None:
-        value = _scalar(stale[0])
+    if "stale_after" in meta:
+        value = _scalar(str(meta["stale_after"]))
         if not value:
             warns.append("`stale_after:` is empty — give an ISO date (YYYY-MM-DD) or drop the field")
         elif not (_ISO_DATE_RE.match(value) or _ISO_DATETIME_RE.match(value)):
@@ -520,8 +534,8 @@ _DOCMAP_SCAFFOLD = """\
 > one line each: what it is and when to read it. A router, not a summary; detail lives in the linked
 > docs. KB notes live beside this file in `{artifact_dir}/kb/`.
 >
-> **Discipline:** kept honest by [`check_doc_coverage.py`](../../scripts/check_doc_coverage.py) —
-> every link here must resolve (a link to a missing file is a **hard failure**), and a KB note
+> **Discipline:** kept honest by `check_doc_coverage.py` —
+> every linked table row must resolve (a link to a missing file is a **hard failure**), and a KB note
 > (`{artifact_dir}/kb/*.md`) not indexed here **warns**. Only `{artifact_dir}/kb/*.md` is governed.
 
 ## Read first

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

@@ -347,6 +347,22 @@ def split_diff_by_file(diff_text: str) -> list[str]:
     return parts
 
 
+def changed_paths(diff_text: str) -> list[str]:
+    """The post-change path of every file in the diff, in diff order."""
+    paths: list[str] = []
+    for chunk in split_diff_by_file(diff_text):
+        header = chunk.split("\n", 1)[0].rstrip("\r")
+        if not header.startswith("diff --git "):
+            continue
+        rest = header[len("diff --git "):]
+        quoted = rest.rfind(' "b/')
+        if rest.endswith('"') and quoted != -1:
+            paths.append(rest[quoted + 4:-1])
+        elif " b/" in rest:
+            paths.append(rest.rsplit(" b/", 1)[1])
+    return paths
+
+
 def batch_diff(diff_text: str, max_chars: int) -> list[str]:
     """Pack whole files into as few batches as possible, each under `max_chars`.
 
@@ -398,14 +414,24 @@ def current_branch(cwd: str) -> str:
         return "the current branch"
 
 
-def build_review_prompt(diff_text: str, branch: str, rng: str | None) -> str:
+def build_review_prompt(diff_text: str, branch: str, rng: str | None,
+                        all_paths: list[str] | None = None) -> str:
     """Adversarial review prompt — ported from docket runner._review_prompt (kept in sync).
 
     Self-contained: the criteria are inline so a real review always happens, and it ends with
     a single machine-parseable verdict line the caller maps to an exit code.
     """
     scope = rng or "the working tree (staged, unstaged and new untracked files)"
-    return (
+    part_note = ""
+    if all_paths and len(all_paths) > len(changed_paths(diff_text)):
+        # Without the whole list, a batch reports files it cannot see as missing.
+        part_note = (
+            "This diff is one part of a larger change. The whole change touches these files:\n"
+            + "".join(f"- {p}\n" for p in all_paths)
+            + "Review only the files in the diff below. The other files are reviewed in other "
+            "batches; do not report them as missing.\n\n"
+        )
+    return part_note + (
         f"Perform an adversarial code review of the changes on branch '{branch}' ({scope}). "
         "The unified diff is provided below. Judge, in priority order: (1) correctness — logic "
         "bugs, wrong results, missed edge cases; (2) tests — would a test fail without this "
@@ -731,7 +757,7 @@ def main(argv: list[str] | None = None, env: dict[str, str] | None = None) -> in
         cannot silently shrink a diff to nothing. Returns None when a chunk that cannot be split
         any further still fails — the abort path stays reachable.
         """
-        review = _try_chain(build_review_prompt(chunk, branch, args.range), label)
+        review = _try_chain(build_review_prompt(chunk, branch, args.range, whole_change), label)
         if review is not None:
             return [review]
         files = split_diff_by_file(chunk)
@@ -749,6 +775,7 @@ def main(argv: list[str] | None = None, env: dict[str, str] | None = None) -> in
             out += got
         return out
 
+    whole_change = changed_paths(diff_text)
     verdicts: list[bool | None] = []
     for batch_no, batch in enumerate(batches, 1):
         label = f" (batch {batch_no}/{len(batches)})" if len(batches) > 1 else ""

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

@@ -907,6 +907,8 @@ ARTIFACT_GITIGNORE = """\
 reviews/*.html
 usage-log.jsonl
 agent-log.jsonl
+usage-log.jsonl.1
+agent-log.jsonl.1
 .last-usage-review
 relay.md
 relay/
@@ -914,6 +916,9 @@ session-state.md
 session-state/
 context-window.json
 PROJECT-FACTS.md
+# lock files beside locked documents, and migration backups (never commit these)
+*.lock
+*.bak
 # retired writer; ignored so old files stay untracked
 memory.jsonl
 """

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

@@ -2,7 +2,7 @@
 """caddis /usage-review: local usage analysis + harness self-tuning recommendations.
 
 Reads:
-  <artifact-dir>/usage-log.jsonl  per-session digest (Stop hook). Tries `.caddis/`, then the older
+  <artifact-dir>/usage-log.jsonl  per-session digest (/handoff). Tries `.caddis/`, then the older
                                   `.claude/usage-log.jsonl`.
   ~/.claude/projects/<slug>/      session transcripts (agent dispatches, context size)
   claude-harness/agents/*.md      agent model tiers (frontmatter)
@@ -660,7 +660,7 @@ def render_markdown(metrics: dict, findings: list[dict], days: int,
         f"| Output tokens | {_fmt(metrics['output'])} |",
         f"| Input + cache read | {_fmt(metrics['input'] + metrics['cache_read'])} |",
         f"| Cache efficiency | {_pct(metrics['cache_read'], metrics['input'] + metrics['cache_read'])} read from cache |",
-        f"| Est. cost equiv. | ${metrics['est_cost_usd']:.2f} (estimate; edit rates in session_end.py) |",
+        f"| Est. cost equiv. | ${metrics['est_cost_usd']:.2f} (estimate; edit rates in session_state.py) |",
         "",
         "## Findings",
         "",

package/bundles/antigravity-plugin/session_end_agy.py

@@ -6,7 +6,12 @@ the workspace's usage log (`<workspace>/.caddis/usage-log.jsonl`). Self-containe
 ship claudster_config.py), stdlib-only, and fully defensive:
 a Stop hook must never fail the turn, and must not print a non-JSON line to stdout (agy parses Stop-hook
 stdout as a `{"decision":…}` object — a stray string trips its "unsupported hook decision" path). So this
-does a pure side effect and prints NOTHING.
+does a pure side effect and prints NOTHING: empty stdout is agy's "no decision", while
+`{"decision": "continue"}` would stop the session from ending.
+
+Headless runs (CADDIS_HEADLESS, DOCKET_PLAN or DOCKET_BRANCH set and non-empty) are skipped, as in
+the Claude Stop hook, so review and lane runs leave no files. The record is one append with no
+transcript read, so it stays here rather than moving to /handoff (Phase 13).
 
 agy Stop stdin (camelCase protojson):
   {"executionNum":N, "terminationReason":"model_stop|max_steps_exceeded|error", "error":"",
@@ -60,11 +65,21 @@ def _workspace_roots(data):
         return []
     return [str(r) for r in roots if isinstance(r, (str, bytes)) and str(r).strip()]
 
+_HEADLESS_MARKERS = ("CADDIS_HEADLESS", "DOCKET_PLAN", "DOCKET_BRANCH")
+
+
+def _headless() -> bool:
+    """True when any marker is set to a non-empty value. `CADDIS_HEADLESS=` is not headless."""
+    return any(str(os.environ.get(name, "")).strip() for name in _HEADLESS_MARKERS)
+
+
 def main() -> None:
     try:
         data = json.load(sys.stdin)
     except Exception:
         data = {}
+    if _headless():
+        return
     try:
         roots = _workspace_roots(data) or [os.getcwd()]
         # Write the record to every root that ALREADY has a .caddis dir, rather than to

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

@@ -11,65 +11,65 @@
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
-| Api Design | `api-design/` | REST and GraphQL API design patterns. Use when designing new API endpoints, defining resource schemas, planning versioning strategies, or reviewing API contracts. Covers naming conventions, pagination, filtering, error responses, and OpenAPI documentation. |
-| Backend Development | `backend-development/` | Backend API design, database architecture, microservices patterns, and test-driven development. Use for designing APIs, database schemas, or backend system architecture. |
-| Code Review | `code-review/` | Automated code review for pull requests using specialized review patterns. Analyzes code for quality, security, performance, and best practices. Use when reviewing code changes, PRs, or doing code audits. |
-| Codebase Audit | `codebase-audit/` | Systematic codebase audit methodology for unfamiliar codebases before architecture or implementation work. Use for new codebase, unfamiliar codebase, pre-implementation audit, codebase review, technical due diligence, or onboarding to an existing project. Produces AUDIT-FINDINGS.md and QUESTIONS.md. Routes to Architect, Planner, or Code Reviewer agents. |
+| Api Design | `api-design/` | REST and GraphQL API design: endpoints, resource schemas, versioning, pagination, error responses, OpenAPI. Use when designing or reviewing API contracts. |
+| Backend Development | `backend-development/` | Backend API design, database schemas, microservices and TDD. Use for backend system architecture. |
+| Code Review | `code-review/` | Automated code review for quality, security, performance and best practices. Use when reviewing code changes, PRs, or doing code audits. |
+| Codebase Audit | `codebase-audit/` | Audit an unfamiliar codebase before architecture or implementation work. Use for a new codebase, pre-implementation audit, codebase review, technical due diligence or onboarding. Produces AUDIT-FINDINGS.md and QUESTIONS.md. |
 | Cross Review | `cross-review/` | Cross-vendor code review of the current diff — a second-vendor model (DeepSeek/GLM/any OpenAI-compatible endpoint) reviews your changes to catch bugs a same-vendor reviewer misses |
-| Dashboard Perf Sweep | `dashboard-perf-sweep/` | Re-measure an app's dashboard/API endpoints for load-time regressions and decide, with a documented checklist (not a black-box verdict), whether a slow one is a candidate for the rs-kit summary-table refresher pattern — or needs an index, keyset paging, gzip, or nothing at all. Use when the user says "sweep dashboard performance", "check if this app needs rs-kit", "re-measure the perf tracker", "is this endpoint a refresher candidate", or when a dashboard-performance-tracker.md is stale and needs re-validating. Read-only by default (dev servers only; prod requires an explicit opt-in and human confirmation) and human-invoked, never scheduled -- it surfaces candidates, it does not enroll them. |
-| Error Handling | `error-handling/` | Error handling patterns for Python and TypeScript applications. Use when designing error hierarchies, implementing retry logic, building error boundaries, or establishing logging strategies. Covers custom exceptions, result types, circuit breakers, and user-facing error messages. |
+| Dashboard Perf Sweep | `dashboard-perf-sweep/` | Re-measure dashboard/API endpoints for load-time regressions and decide by checklist if a slow one needs the rs-kit refresher, an index, keyset paging, gzip, or nothing. Use when the user says "sweep dashboard performance", "check if this app needs rs-kit", "re-measure the perf tracker", "is this endpoint a refresher candidate", or dashboard-performance-tracker.md is stale. Read-only. |
+| Error Handling | `error-handling/` | Error handling for Python and TypeScript: error hierarchies, custom exceptions, result types, retries, circuit breakers, error boundaries, logging, user-facing messages. |
 | Fastapi Dev | `fastapi-dev/` | Build FastAPI backends with standard patterns, error handling, and testing |
 | Javascript Typescript | `javascript-typescript/` | JavaScript and TypeScript development with ES6+, Node.js, React, and modern web frameworks. Use for frontend, backend, or full-stack JavaScript/TypeScript projects. |
-| Python Development | `python/` | Modern Python development with Python 3.12+, Django, FastAPI, async patterns, and production best practices. Use for Python projects, APIs, data processing, or automation scripts. |
+| Python Development | `python/` | Modern Python 3.12+ (Django, FastAPI, async) with production best practices. Use for Python projects, APIs, data processing or scripts. |
 | Refactoring | `refactoring/` | Safely refactor code while maintaining behavior. Use when improving code structure, reducing duplication, extracting functions, or modernizing legacy code. |
 | Security Review | `security-review/` | Security review workflow — OWASP, code scanning, cloud infrastructure |
-| Sql | `sql/` | Write high-quality, optimized SQL with best practices for performance, NULL handling, security, and readability. Database-agnostic patterns with dialect-specific notes. |
+| Sql | `sql/` | Write optimized, secure, readable SQL: performance, NULL handling, dialect-specific notes. |
 
 ### Data
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
-| Database Design | `database-design/` | Database schema design, optimization, and migration patterns for PostgreSQL, MySQL, and NoSQL databases. Use for designing schemas, writing migrations, or optimizing queries. |
-| Db Diagram | `db-diagram/` | Turn a SQL artifact — a stored procedure, view, query, .sql file, or table name — into a diagram that explains it to a human. Use when the user says "diagram this query/proc/view/schema", "explain this SQL visually", "draw the ER diagram", "show me the data flow of this stored proc", "/mermaid-db", or "/excalidraw-db". Produces Mermaid (default, git-diffable) or Excalidraw (for design reviews). Read-only — never touches the database. |
+| Database Design | `database-design/` | Database schema design, migrations and query optimization for PostgreSQL, MySQL and NoSQL. |
+| Db Diagram | `db-diagram/` | Diagram a SQL artifact (stored proc, view, query, .sql file, table) as Mermaid or Excalidraw. Use when the user says "diagram this query/proc/view/schema", "explain this SQL visually", "draw the ER diagram", "show me the data flow of this stored proc", "/mermaid-db", or "/excalidraw-db". Read-only. |
 
 ### Devops
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
-| Adopt App | `adopt-app/` | Bring an app that was never scaffolded - a proof of concept that became real, a folder on a server, a checkout with no remote - up to the standard a generated app starts at. Inventories it without running it (local folder, network share, or a remote Windows box over WinRM), works out what stack each component is, measures it against an adoption standard with three verdicts (pass, gap, and question-only-a-person-can-answer), and writes an ordered plan whose steps cannot be done in the wrong order. Use when the user says "this app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on the server", "bring this up to standard", "what would it take to get this into CI", "nobody knows how this is deployed", or "it started as a prototype and now it is production". |
-| Ci Cd Pipeline | `ci-cd-pipeline/` | CI/CD pipeline design and implementation for GitHub Actions, Azure DevOps, and general pipeline architecture. Use when creating build pipelines, deployment workflows, quality gates, environment promotion strategies, or automating release processes. |
+| Adopt App | `adopt-app/` | Bring an app that was never scaffolded (POC, server folder, checkout with no remote) up to standard — inventory without running it, pass/gap/question verdicts, ordered plan. Use when the user says "this app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on the server", "bring this up to standard", "what would it take to get this into CI", "nobody knows how this is deployed", or "it started as a prototype and now it is production". |
+| 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. |
 | Gh Cli | `gh-cli/` | GitHub CLI operations — issues, PRs, releases, and repo management |
 | Git Commit | `git-commit/` | Create well-structured conventional commit messages following Conventional Commits standard. Use when committing changes, preparing PRs, or generating changelogs. |
-| Port To Github | `port-to-github/` | Move (port) an app or repository to GitHub from ANY source - a Gitea/GitLab/any git server URL, a local folder, a network (UNC) share, or a folder on a remote Windows box reached over WinRM - with or without existing git history. Keeps every branch and tag, verifies by SHA, translates Gitea/Forgejo Actions CI, enforces a source-only content policy (runtimes, binaries, data exports and dependencies stay out of the repo, over ALL history, with a runtime manifest and provisioning script so the environment is still reproducible), switches deploy checkouts to GitHub with automatic rollback, and retires the old host safely. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", "keep binaries / MariaDB / PHP out of the repo", "check the repo only holds source", or "cut the deploy over to GitHub". |
-| Safe Cleanup | `safe-cleanup/` | Use BEFORE deleting any directory tree, clearing a scratchpad, removing git worktrees, or "tidying up" generated folders - especially on Windows, where a recursive delete that meets a junction or symlink destroys the link's TARGET. Also use when verifying that a Python venv or node_modules survived a cleanup, because pip check and file counts both report healthy on a half-deleted environment. |
-| Using Git Worktrees | `using-git-worktrees/` | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification |
-| Windows Deployment | `windows-deployment/` | Deploy FastAPI + React/Vite apps to Windows Server with NSSM services, reverse proxy (IIS or nginx), and git-pull workflow. Use when deploying any web app to a Windows prod server, setting up NSSM services, configuring IIS or nginx reverse proxy, making code environment-aware for dev/prod, or troubleshooting prod deployment issues. |
+| Port To Github | `port-to-github/` | Port an app or repo to GitHub from any source (git server, local folder, UNC share, Windows box over WinRM) — all branches and tags, SHA-verified, CI translated, history kept source-only, deploy cut over with rollback. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from Gitea", "put this folder on GitHub", "this app only exists on the server", "import the repo from the prod box", "keep binaries / MariaDB / PHP out of the repo", "check the repo only holds source", or "cut the deploy over to GitHub". |
+| 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. |
+| 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. |
+| Windows Deployment | `windows-deployment/` | Deploy FastAPI + React/Vite apps to Windows Server with NSSM services, IIS or nginx reverse proxy and git-pull. Use for Windows prod deploys, NSSM, reverse proxy setup, dev/prod config, or prod troubleshooting. |
 
 ### Docs
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
-| Code Documentation | `code-documentation/` | Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides. |
-| Confluence Hla | `confluence-hla/` | Author enterprise High-Level Architecture (HLA) documents in Simplified Technical English and generate Confluence Storage Format XHTML with self-contained PlantUML diagrams, wrapped tables, and zero AI fingerprints. Use when creating high-level architecture designs, architecture documentation for Confluence, or converting markdown architecture to Confluence storage format. |
+| Code Documentation | `code-documentation/` | Write code documentation: API docs, README files, inline comments and developer guides. |
+| Confluence Hla | `confluence-hla/` | High-Level Architecture (HLA) documents in Simplified Technical English as Confluence Storage Format XHTML with PlantUML. Use for Confluence architecture docs or converting markdown architecture. |
 | Data Lineage | `data-lineage/` | Generate End-to-End Data Lineage and Telemetry Specification Markdown and Confluence XHTML for fleet observability. |
-| Explainer Doc | `explainer-doc/` | Write a document that hands off work to a team who did NOT do the investigation — an external vendor, another team, a contractor — and who must be able to act on it alone. Use when the user says "write a spec for the X team", "document this for someone outside the team", "explainer doc", "implementation spec for a vendor", "hand this off to Y", or is about to write a design doc whose primary reader did not live through the debugging/design process. NOT for internal specs where the reader already has full context (use technical-writing or writing-plans instead) — this is specifically for the "stranger must follow it alone" case. |
+| Explainer Doc | `explainer-doc/` | Hand-off doc for a team that did NOT do the investigation (vendor, contractor, another team) — the "stranger must follow it alone" case. Use when the user says "write a spec for the X team", "document this for someone outside the team", "explainer doc", "implementation spec for a vendor", or "hand this off to Y". Not for readers with full context. |
 | Hld | `hld/` | Generate High-Level Design (HLD) Markdown documentation and Confluence XHTML with native PlantUML diagrams. |
 | Lld | `lld/` | Generate Lower-Level Design (LLD) Markdown documentation and Confluence XHTML with native PlantUML diagrams. |
 | Tech Explainer | `tech-explainer/` | >- |
-| Technical Writing | `technical-writing/` | Technical documentation best practices for READMEs, API docs, architecture docs, runbooks, and developer guides. Use when writing or reviewing documentation, creating onboarding guides, or establishing documentation standards. |
+| 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 |
 
 ### Frontend
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
-| Css Architecture | `css-architecture/` | CSS architecture, design token strategy, Tailwind conventions, CSS Modules, container queries, dark mode, responsive patterns, and animation architecture. Use for design token naming, CSS custom properties, Tailwind config, container queries, dark mode implementation, fluid typography, or CSS animation decisions. Complements frontend-design (what to achieve) with how to implement it. |
-| Frontend Design | `frontend-design/` | Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications. Generates creative, polished code that avoids generic AI aesthetics while strictly adhering to the user's technical standards. |
+| Css Architecture | `css-architecture/` | CSS architecture: design tokens, custom properties, Tailwind config, CSS Modules, container queries, dark mode, fluid typography, animation. Covers how to implement styling; frontend-design covers what to achieve. |
+| Frontend Design | `frontend-design/` | Create distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters or applications. |
 | Mockup | `mockup/` | Create framework-aware UI mockups with feasibility checks. Prevents wasted effort by validating that proposed designs work within the target framework's constraints. |
 | React Best Practices | `react-best-practices/` | Modern React development guidelines covering hooks, component patterns, state management, performance optimization, and TypeScript integration. |
-| React Dev | `react-dev/` | This skill should be used when building React components with TypeScript, typing hooks, handling events, or when React TypeScript, React 19, Server Components are mentioned. Covers type-safe patterns for React 18-19 including generic components, proper event typing, and routing integration (TanStack Router, React Router). |
-| Ui Review | `ui-review/` | Review UI implementations against design requirements, accessibility standards (WCAG 2.2 AA), and brand guidelines. Use when reviewing designs or validating UI before release. |
-| Warm Editorial Ui | `warm-editorial-ui/` | Apply the "Warm Editorial Refinement" design system — a sophisticated, executive-grade aesthetic with warm cream surfaces (light mode) and warm charcoal surfaces (dark mode), Bahnschrift + Plus Jakarta Sans typography, generous rounded corners, multi-layer shadows, and a warm neutral palette. Supports both light and dark themes via CSS custom properties and the `.dark` class. Use this skill whenever the user wants to build an app, dashboard, component, or web UI using the abc-project visual style. Trigger on phrases like "use our design system", "apply our template", "make it look like abc-project", "use the warm editorial style", "use our brand template", "add dark mode", or any request to build a new tool/app/dashboard for XYZ Brand or similar contexts. This is the canonical design template for all new frontend builds. |
+| React Dev | `react-dev/` | Type-safe React 18-19 with TypeScript: components, generic components, hooks, events, Server Components, TanStack Router and React Router. Use when React TypeScript or React 19 is involved. |
+| Ui Review | `ui-review/` | Review a UI against design requirements, WCAG 2.2 AA and brand guidelines. Use when validating UI before release. |
+| Warm Editorial Ui | `warm-editorial-ui/` | Apply the "Warm Editorial Refinement" design system (warm cream/charcoal surfaces, Bahnschrift + Plus Jakarta Sans, layered shadows), the canonical template for new frontend builds. Use for apps, dashboards or UI in the abc-project style, or on "use our design system", "apply our template", "make it look like abc-project", "use the warm editorial style", "use our brand template", "add dark mode", or a new tool for XYZ Brand. |
 
 ### General
 
@@ -77,6 +77,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 |
+| 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 |
 | Feature Plan | `feature-plan/` | Create a phased, TDD-structured implementation plan that acts as the durable spine for multi-session work |
@@ -93,6 +94,7 @@
 | Park | `park/` | File a future-work item in the one backlog — .caddis/parking-lot/ — or list what is open |
 | 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. |
 | Prd | `prd/` | Capture requirements through structured discovery and write a PRD |
+| Rca | `rca/` | Record a root cause in one step — .caddis/rca/<date>-<slug>.md — or close one with the fixing commit |
 | Resume | `resume/` | Renamed to /caddis:catchup (alias, removed next release) |
 | Review | `review/` | Renamed to /caddis:review-pr (alias, removed next release) |
 | 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. |
@@ -114,26 +116,26 @@
 | Skill | Path | When to Use |
 |-------|------|-------------|
 | Draw Io | `draw-io/` | draw.io diagram creation, editing, and review. Use for .drawio XML editing, PNG conversion, layout adjustment, and AWS icon usage. |
-| Mermaid Diagrams | `mermaid-diagrams/` | Create software diagrams using Mermaid text-based syntax. Use for class diagrams (domain modeling, OOP design), sequence diagrams (API flows, interactions), flowcharts (processes, algorithms, user journeys), ERD (database schemas), C4 architecture diagrams, state diagrams, git graphs, gantt charts, and data visualization. |
-| Particle Art | `particle-art/` | Generate animated particle art React/Next.js components — zero dependencies, spring physics, CSS-variable theming, DPR-correct canvas, mouse interaction. Use when the user wants animated hero art, a living logo, a branded initial or monogram, a constellation background, or any "particles that form a shape". Triggers on "particle animation", "node network", "animated letter/logo/initials", "living letter", "morphing particles", "constellation", "neural net art", "dot field", "stipple portrait", "halftone animation", "ASCII art animation", "background art for my site", or "art that reacts to mouse". Covers — text/initials → spring-node letter; preset patterns (constellation, helix, spiral, DNA, hex-grid, wave, infinity); custom SVG paths; custom polygon points; Unicode halftone stipple; Gaussian dot field with sparks; SVG circuit traces; hybrid combos. Outputs a complete, self-contained, copy-paste-ready React component. Prefer this over p5.js (zero-dep, React-native, TypeScript), tsParticles (richer spring physics, CSS-var theming), Three.js (lightweight, no WebGL). |
+| Mermaid Diagrams | `mermaid-diagrams/` | Software diagrams in Mermaid: class, sequence, flowchart, ERD, C4, state, git graph, gantt. Use for domain models, API flows, processes and database schemas. |
+| Particle Art | `particle-art/` | Zero-dependency animated particle art as a React/Next.js component (spring physics, CSS-variable theming, mouse interaction). Use for animated hero art or a living logo, or on "particles that form a shape", "particle animation", "node network", "animated letter/logo/initials", "living letter", "morphing particles", "constellation", "neural net art", "dot field", "stipple portrait", "halftone animation", "ASCII art animation", "background art for my site", or "art that reacts to mouse". |
 
 ### Testing
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
-| Playwright | `playwright/` | Complete browser automation with Playwright. Auto-detects dev servers, writes clean test scripts to /tmp. Test pages, fill forms, take screenshots, check responsive design, validate UX, test login flows, check links, automate any browser task. Use when user wants to test websites, automate browser interactions, validate web functionality, or perform any browser-based testing. |
+| Playwright | `playwright/` | Browser automation and testing with Playwright: auto-detects dev servers; tests pages, forms, logins, links, screenshots and responsive layouts. Use to test websites or automate any browser task. |
 | Tdd Workflow | `tdd-workflow/` | Test-Driven Development workflow — red-green-refactor cycle |
-| Test Strategy | `test-strategy/` | Test planning and strategy for projects of any size. Use when defining what to test, choosing test types, setting coverage goals, building test pyramids, or planning quality gates. Produces TEST-STRATEGY.md with prioritized test plan. Routes to Tester agent for execution. |
-| Webapp Testing | `webapp-testing/` | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. |
+| Test Strategy | `test-strategy/` | Plan what to test: test types, coverage goals, test pyramid, quality gates. Produces a prioritized TEST-STRATEGY.md for the Tester agent. |
+| Webapp Testing | `webapp-testing/` | Test local web apps with Playwright: verify frontend behavior, debug UI, capture screenshots and browser logs. |
 
 ### Workflow
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
-| Advisory Hub | `advisory-hub/` | Cross-session phase validation for multi-phase implementation plans — a long-lived "Hub" session RE-DERIVES each implementation phase's claims independently instead of trusting its self-assessment. Use when the user says "advisory hub", "validate this phase", "phase report", "hub verdict", "advisory context", "who checks the implementing session", "the plan turned out to be wrong", "hand off the hub", "re-derive don't trust", or when a long, multi-session plan with expensive-to-reverse decisions (a migration, a security change, anything touching production data correctness) needs an independent session that verifies every phase before the next one starts. NOT for a three-phase feature — it costs a full extra session's context per phase, and a skill that doesn't say so gets applied everywhere and resented. Every Hub artefact belongs in `.caddis/advisory-hub-reports/` — a succession prompt is `hub-NN.spawn.md` there, never a generic prompts folder, even when you write it by hand instead of running `/caddis:spawn-hub`. |
+| Advisory Hub | `advisory-hub/` | A long-lived "Hub" session re-derives each phase of a multi-session plan instead of trusting its self-report. Use when the user says "advisory hub", "validate this phase", "phase report", "hub verdict", "advisory context", "who checks the implementing session", "the plan turned out to be wrong", "hand off the hub", "re-derive don't trust", or a long plan with expensive-to-reverse work (a migration, a security change, production data correctness) needs independent checks; not for short features. Hub artefacts, including `hub-NN.spawn.md`, go in `.caddis/advisory-hub-reports/`. |
 | Best Practices | `best-practices/` | >- |
 | 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. |
 | Context Curator | `context-curator/` | Compress and prioritize codebase context before handing work to reasoning agents, minimizing token waste while preserving the required decision inputs. |
 | Preflight | `preflight/` | Plan-vs-codebase validation — verifies API contracts, type names, field accuracy, dependencies, and paths before implementation begins |
 | Setup Project Ai | `setup-project-ai/` | Install or refresh the agent-agnostic dev harness in this project (AGENTS.md-canonical rules hierarchy + CLAUDE.md @import shims, subagents, commands, settings) |
-| Skill Creator | `skill-creator/` | Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. |
+| Skill Creator | `skill-creator/` | Create, edit and improve skills, run evals and benchmarks, and optimize a skill's description for triggering accuracy. |

package/bundles/antigravity-plugin/skills/adopt-app/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: adopt-app
-description: Bring an app that was never scaffolded - a proof of concept that became real, a folder on a server, a checkout with no remote - up to the standard a generated app starts at. Inventories it without running it (local folder, network share, or a remote Windows box over WinRM), works out what stack each component is, measures it against an adoption standard with three verdicts (pass, gap, and question-only-a-person-can-answer), and writes an ordered plan whose steps cannot be done in the wrong order. Use when the user says "this app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on the server", "bring this up to standard", "what would it take to get this into CI", "nobody knows how this is deployed", or "it started as a prototype and now it is production".
+description: Bring an app that was never scaffolded (POC, server folder, checkout with no remote) up to standard — inventory without running it, pass/gap/question verdicts, ordered plan. Use when the user says "this app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on the server", "bring this up to standard", "what would it take to get this into CI", "nobody knows how this is deployed", or "it started as a prototype and now it is production".
 ---
 
 # adopt-app

package/bundles/antigravity-plugin/skills/advisory-hub/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: advisory-hub
-description: Cross-session phase validation for multi-phase implementation plans — a long-lived "Hub" session RE-DERIVES each implementation phase's claims independently instead of trusting its self-assessment. Use when the user says "advisory hub", "validate this phase", "phase report", "hub verdict", "advisory context", "who checks the implementing session", "the plan turned out to be wrong", "hand off the hub", "re-derive don't trust", or when a long, multi-session plan with expensive-to-reverse decisions (a migration, a security change, anything touching production data correctness) needs an independent session that verifies every phase before the next one starts. NOT for a three-phase feature — it costs a full extra session's context per phase, and a skill that doesn't say so gets applied everywhere and resented. Every Hub artefact belongs in `.caddis/advisory-hub-reports/` — a succession prompt is `hub-NN.spawn.md` there, never a generic prompts folder, even when you write it by hand instead of running `/caddis:spawn-hub`.
+description: A long-lived "Hub" session re-derives each phase of a multi-session plan instead of trusting its self-report. Use when the user says "advisory hub", "validate this phase", "phase report", "hub verdict", "advisory context", "who checks the implementing session", "the plan turned out to be wrong", "hand off the hub", "re-derive don't trust", or a long plan with expensive-to-reverse work (a migration, a security change, production data correctness) needs independent checks; not for short features. Hub artefacts, including `hub-NN.spawn.md`, go in `.caddis/advisory-hub-reports/`.
 ---
 
 # Advisory Hub — cross-session phase validation

package/bundles/antigravity-plugin/skills/api-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-design
-description: REST and GraphQL API design patterns. Use when designing new API endpoints, defining resource schemas, planning versioning strategies, or reviewing API contracts. Covers naming conventions, pagination, filtering, error responses, and OpenAPI documentation.
+description: "REST and GraphQL API design: endpoints, resource schemas, versioning, pagination, error responses, OpenAPI. Use when designing or reviewing API contracts."
 ---
 
 # API Design Skill

package/bundles/antigravity-plugin/skills/backend-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backend-development
-description: Backend API design, database architecture, microservices patterns, and test-driven development. Use for designing APIs, database schemas, or backend system architecture.
+description: Backend API design, database schemas, microservices and TDD. Use for backend system architecture.
 source: wshobson/agents
 license: MIT
 ---

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

@@ -5,9 +5,9 @@ description: Where were we? A quick list of what this session was doing and what
 
 # /catchup — where are we?
 
-If $ARGUMENTS is empty, follow the catchup procedure below. If a name is given, follow
-the pop-and-resume procedure at the end of this file. The name selects this mode; the
-procedure still pops the last parked frame.
+If $ARGUMENTS is empty, follow the catchup procedure below. If a workstream name is given,
+load that workstream's relay (the named-load procedure at the end of this file). Loading
+never removes or changes the relay.
 
 Answer one question: **what were we doing, and what is still open?**
 
@@ -62,36 +62,34 @@ on is worse than one sentence admitting there is nothing to recap.
   folder, or `claude --resume` to pick an older session. Mention this only if the recap is thin,
   or if they ask for detail the files do not hold.
 - To **write** a durable resume doc rather than read one: `/caddis:handoff`.
-- To **pop a parked workstream** off the digress stack: `/caddis:catchup [name]`. This restores work deliberately set aside.
-
-# /caddis:catchup [name] — pop the parked task and pick it back up
-
-A digression is finished; return to the task you parked with `/digress`. This pops the top frame off the
-workstream stack, restates where you were, realigns `relay.md`, and immediately continues the work — the
-user should not have to remember or re-state anything.
-
-## Step 1 — read the stack
-Read `.caddis/workstreams.json`. If it is **absent, unparseable, `version != 1`, or `stack` is empty**,
-say exactly `Nothing is parked.` and stop. Do nothing else.
-
-## Step 2 — pop the top frame
-The top of stack is the **last** element of `stack` (LIFO — most recently parked). Remove it and write the
-rest of the file back (preserve `version` and any other frames + unknown fields). This is the one write
-this command makes to the state file.
-
-## Step 3 — restate + realign relay.md
-Restate the popped frame to the user: its `plan`, `phase`, and `resumePointer` (and `repo` if set — the
-parked task lives in another repo, so say which). Then edit `.caddis/relay.md`'s `## Next step` section
-**in place** so it matches the popped frame's `resumePointer` — preserve every other section of relay.md
-untouched. (If relay.md or that section is absent, skip this edit silently; the restatement above is enough.)
-
-## Step 4 — resume the work
-Begin executing the `resumePointer` immediately. Ask nothing — the frame already carries the next action.
-If the parked plan lives in another `repo`, note that the user may need to open that repo first, then
-proceed there.
+- To **switch to a named workstream**: `/caddis:catchup <name>`. This restores or loads the named relay.
+
+## Workstreams and open work
+
+**No argument:** this is the last step of the catchup procedure above, not a separate one.
+After the list, add the workstream index and the open work:
+1. Refresh and show the index: `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" render-index`,
+   then display `.caddis/relay.md`. If it refuses a legacy `.caddis/relay.md`, display that file
+   as it is and suggest `/handoff`, which migrates it.
+2. Show open work for the current workstream:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_todo.py" open-work
+   ```
+Before saying `Nothing is parked.`, check for an old `/digress` stack: if `.caddis/workstreams.json`
+exists, run `caddis_workstreams.py migrate-legacy` (it keeps a backup and reports conflicts
+instead of overwriting), then show the index again. Only with no relays and no old stack, state:
+`Nothing is parked.`
+
+**Named load** (`/catchup <name>`):
+1. Load it: `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" read <name>`.
+2. If it prints nothing, the relay may be on another machine. Ask before fetching, then run
+   `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_relay_git.py" fetch <name>`. It reads only
+   `refs/caddis/relay/<name>`, never checks out or merges, and refuses to replace a different local
+   relay. Pass `--replace` only if the user confirms the local one may be overwritten.
+3. Restate where you were and resume the workstream.
 
 ## Rules
 - **Never** run a destructive or history-rewriting git action (no `git checkout`, `git reset`, `git stash`,
-  branch switches). Resuming is metadata-only.
-- Pop exactly one frame per invocation (the LIFO top). Run `/caddis:catchup [name]` again to pop the next.
-- Only real paths and verified facts — restate the frame as written; do not embellish the resume point.
+  branch switches), even when the loaded workstream names another branch. Resuming is metadata-only:
+  this checkout may be shared with other live sessions. Tell the user which branch it is on instead.
+- Only real paths and verified facts — restate the relay as written; do not embellish the resume point.

package/bundles/antigravity-plugin/skills/ci-cd-pipeline/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ci-cd-pipeline
 context: fork
-description: CI/CD pipeline design and implementation for GitHub Actions, Azure DevOps, and general pipeline architecture. Use when creating build pipelines, deployment workflows, quality gates, environment promotion strategies, or automating release processes.
+description: "CI/CD pipelines for GitHub Actions and Azure DevOps: build and deploy workflows, quality gates, environment promotion and release automation."
 ---
 
 # CI/CD Pipeline Skill

package/bundles/antigravity-plugin/skills/code-documentation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-documentation
-description: Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides.
+description: "Write code documentation: API docs, README files, inline comments and developer guides."
 source: wshobson/agents
 license: MIT
 ---

package/bundles/antigravity-plugin/skills/code-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: code-review
 context: fork
-description: Automated code review for pull requests using specialized review patterns. Analyzes code for quality, security, performance, and best practices. Use when reviewing code changes, PRs, or doing code audits.
+description: Automated code review for quality, security, performance and best practices. Use when reviewing code changes, PRs, or doing code audits.
 source: anthropics/claude-code
 license: Apache-2.0
 ---

package/bundles/antigravity-plugin/skills/codebase-audit/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: codebase-audit
 context: fork
-description: Systematic codebase audit methodology for unfamiliar codebases before architecture or implementation work. Use for new codebase, unfamiliar codebase, pre-implementation audit, codebase review, technical due diligence, or onboarding to an existing project. Produces AUDIT-FINDINGS.md and QUESTIONS.md. Routes to Architect, Planner, or Code Reviewer agents.
+description: Audit an unfamiliar codebase before architecture or implementation work. Use for a new codebase, pre-implementation audit, codebase review, technical due diligence or onboarding. Produces AUDIT-FINDINGS.md and QUESTIONS.md.
 ---
 
 # Codebase Audit Skill

package/bundles/antigravity-plugin/skills/confluence-hla/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: confluence-hla
-description: Author enterprise High-Level Architecture (HLA) documents in Simplified Technical English and generate Confluence Storage Format XHTML with self-contained PlantUML diagrams, wrapped tables, and zero AI fingerprints. Use when creating high-level architecture designs, architecture documentation for Confluence, or converting markdown architecture to Confluence storage format.
+description: High-Level Architecture (HLA) documents in Simplified Technical English as Confluence Storage Format XHTML with PlantUML. Use for Confluence architecture docs or converting markdown architecture.
 ---
 
 # Confluence High-Level Architecture (HLA) Authoring Skill