@caddis/cli 0.0.0 → 0.1.0

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

@@ -0,0 +1,61 @@
+---
+name: digress
+description: Park the current workstream on the stack and switch to a new task — without losing the original
+---
+
+# /caddis:digress — park the current task, switch, never lose the thread
+
+You are about to leave the current task for a related-but-different one (a design decision, a sub-feature,
+or a blocker that must be fixed first). This command **records the original task on a workstream stack** so
+neither you nor the user has to remember and re-state it later — `/resume` pops it back with its exact
+resume point, and every SessionStart surfaces it (`⛏ Parked workstream: …`).
+
+The reason for the detour is **$ARGUMENTS** (if empty, derive a one-line reason yourself from what the
+user just asked for).
+
+## Step 1 — identify the CURRENT workstream (the thing being parked)
+Determine the active plan, in this order:
+1. The `.caddis/plans/*.md` this session has been executing.
+2. Else the plan named in `.caddis/relay.md`'s `## Next step`.
+3. Else — and ONLY if still ambiguous — ask the user which plan to park. This is the **single permitted
+   question**; do not ask anything else.
+
+Read that plan's `## Tracker` (or its phase headings) to find the **current phase** (the in-progress or
+next-not-started one).
+
+## Step 2 — write a one-line `resumePointer`
+The single next concrete action for the parked task — copy it from the plan's Tracker or from relay.md's
+`## Next step`. Example: `next: wire the parser to the staging table (see plan Tracker row 2)`.
+
+## Step 3 — push the frame onto `.caddis/workstreams.json`
+The state file is a JSON object `{"version": 1, "stack": [ … ]}`; `stack` is LIFO (last element = most
+recently parked). Each frame has exactly these fields:
+
+```json
+{
+  "plan": ".caddis/plans/<slug>.md",
+  "phase": "<current phase>",
+  "resumePointer": "<the one-line next action from Step 2>",
+  "reason": "<$ARGUMENTS or your derived one-liner>",
+  "repo": null,
+  "pushedAt": "<now, ISO-8601 UTC>"
+}
+```
+
+- `repo`: `null` means "the plan lives in THIS repo". If the parked plan lives in a **different** repo, set
+  `repo` to that repo's absolute path (the digression spanned repos).
+- Read the file (create `{"version": 1, "stack": []}` if absent). **Idempotency guard:** if the
+  top-of-stack frame's `plan` already equals the plan you are parking, UPDATE that frame in place (refresh
+  `phase`, `resumePointer`, `reason`, `pushedAt`) instead of pushing a duplicate. Otherwise APPEND the new
+  frame. Preserve any unknown fields already present. Write the whole file back (pretty-printed is fine).
+
+## Step 4 — confirm, then continue
+Tell the user: `Parked: <plan> @ <phase>. Now switching to: <the new task>.` Then proceed with whatever the
+user asked — the digression IS the new work.
+
+## Rules
+- **Never** run a destructive or history-rewriting git action (no `git checkout`, `git reset`, `git stash`,
+  branch switches). Parking is metadata-only; the working tree is untouched.
+- Only real paths and verified facts in the frame. If you truly cannot determine the phase, write `"?"` —
+  never invent one.
+- This command records state and switches focus; it does not commit code.

package/bundles/antigravity-plugin/skills/draw-io/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: draw-io
+context: fork
+description: draw.io diagram creation, editing, and review. Use for .drawio XML editing, PNG conversion, layout adjustment, and AWS icon usage.
+---
+
+# draw.io Diagram Skill
+
+**Works with:** Any AI coding agent (Claude, Cursor, GitHub Copilot, Windsurf, etc.)
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Convert to PNG | `bash scripts/convert-drawio-to-png.sh file.drawio` |
+| Find AWS icon | `python scripts/find_aws_icon.py ec2` |
+| List all icons | `python scripts/find_aws_icon.py --list-all` |
+| Direct export | `drawio -x -f png -s 2 -t -o out.png in.drawio` |
+
+## Core Rules
+
+### File Handling
+- Edit only `.drawio` files (XML format)
+- Never edit `.drawio.png` directly
+- Always verify PNG output after changes
+- After edits, validate XML structure before handing off
+
+### Fonts
+- Set `defaultFontFamily` in `<mxGraphModel>` tag
+- Set `fontFamily` in each text element's style
+- Use 18px+ for presentations, 14px minimum
+
+### Background
+- Remove `background="#ffffff"` attribute
+- Use `page="0"` for transparent background
+
+### Arrows
+- **Critical**: Place arrows after title, before other elements
+- Maintain 20px clearance from labels
+- Use explicit coordinates for text element connections
+- For flow edges, set explicit arrowheads and stroke styling:
+  - `endArrow=block;endFill=1`
+  - `strokeColor=<visible color>;strokeWidth>=1`
+
+### XML Structure (Critical)
+- **Never nest `mxCell` inside another `mxCell`; all `mxCell` entries must be direct children of `<root>`.**
+- **Edge labels must be separate sibling `mxCell` nodes with `parent` set to the edge id.**
+- Keep only geometry/content tags (for example `mxGeometry`) inside a given `mxCell`.
+
+### Viewport and Coordinates
+- Use sane viewport defaults: keep `dx`/`dy` near 0.
+- Ensure page dimensions cover the full drawing bounds (`pageWidth`/`pageHeight` large enough).
+- Keep nodes/points in positive in-canvas coordinates unless there is an explicit reason not to.
+- If a diagram opens off-screen, normalize coordinates and reset `dx`/`dy` before finalizing.
+
+### Container Margins
+- **Must**: 30px minimum margin from frame boundaries
+- Calculate: element top ≥ frame.y + 30
+- Calculate: element bottom ≤ frame.y + frame.height - 30
+
+### Text Width
+- English: ~10px per character + 20px padding
+- For "Application Server" (18 chars): ~200px width
+
+## XML Structure
+
+```xml
+<mxGraphModel defaultFontFamily="Arial" page="0">
+  <!-- Title (always first) -->
+  <mxCell id="title" value="Diagram Title" .../>
+  
+  <!-- Arrows (back layer) -->
+  <mxCell id="arrow1" style="edgeStyle=..." edge="1">
+    <mxGeometry relative="1">
+      <mxPoint x="100" y="200" as="sourcePoint"/>
+      <mxPoint x="500" y="200" as="targetPoint"/>
+    </mxGeometry>
+  </mxCell>
+  
+  <!-- Elements (front layer) -->
+  <mxCell id="box1" .../>
+</mxGraphModel>
+```
+
+## AWS Icons
+
+Use latest `mxgraph.aws4.*` icons:
+
+```xml
+<!-- Resource icon -->
+style="shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.ec2;"
+
+<!-- Official names -->
+value="Amazon ECS"  <!-- Not "ECS" -->
+value="AWS Lambda"  <!-- Not "Lambda" -->
+```
+
+Find icons: `python scripts/find_aws_icon.py <service>`
+
+## Layout Calculations
+
+**Align elements vertically:**
+```
+Box 1: y=100, height=80 → center = y + h/2 = 140
+Box 2: y=120, height=40 → center = y + h/2 = 140
+Result: Aligned ✓
+```
+
+**Container margin check:**
+```
+Frame: y=20, height=400 → range 20-420
+Element: y=50 → margin from top = 50-20 = 30px ✓
+Element: y+h=390 → margin from bottom = 420-390 = 30px ✓
+```
+
+## Common Fixes
+
+**Overlapping arrows:** Move arrow XML after title, before elements
+**Text cut off:** Increase `width` in mxGeometry
+**No PNG output:** Check `drawio --version`, install if missing
+**Element overflow:** Verify 30px margins from container
+**Could not add object for mxCell:** flatten malformed nested `mxCell` nodes into root-level siblings
+**Diagram opens out of sight:** reset `dx`/`dy` close to 0 and move all key geometries to positive coordinates
+**Arrows not visible:** add `endArrow=block;endFill=1` and explicit `strokeColor` on each flow edge
+
+## Required Validation (Post-Edit)
+
+Run these checks after every `.drawio` XML edit:
+
+1. **Well-formed XML parse**
+  - Parse the file with an XML parser and ensure no syntax errors.
+2. **Nested-`mxCell` structural check**
+  - Confirm no `mxCell` contains a child `mxCell`.
+3. **Viewport/canvas sanity check**
+  - Verify `dx`/`dy` are sane and geometry coordinates are not unintentionally far negative.
+4. **Edge visibility check**
+  - For flow diagrams, confirm edges include explicit arrowheads and visible stroke colors.
+5. **Visual open test**
+  - Open in draw.io and ensure diagram is visible at normal zoom without manual panning.
+
+## Quality Checklist
+
+- [ ] `page="0"` (no background)
+- [ ] Font size 18px+ for presentations
+- [ ] Arrows at back layer
+- [ ] Flow edges use explicit arrowheads (`endArrow=block;endFill=1`) and visible stroke colors
+- [ ] 30px+ margins from frames
+- [ ] No nested `mxCell` nodes (all cells are root-level siblings)
+- [ ] Edge labels are sibling `mxCell` nodes with `parent=<edge_id>`
+- [ ] `dx`/`dy` near 0 and page size fits diagram bounds
+- [ ] Main nodes/points are in positive in-canvas coordinates
+- [ ] Official service names (Amazon ECS, AWS Lambda)
+- [ ] Latest icons (aws4, not aws3)
+- [ ] PNG visually verified
+
+## Extended Documentation
+
+See `references/` directory for:
+- Layout patterns and best practices
+- Complete AWS icon catalog
+- Detailed troubleshooting
+- CI/CD integration examples