@caddis/cli 0.4.92 → 0.4.94

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 (99) hide show
  1. package/README.md +4 -0
  2. package/bundles/antigravity-plugin/agents/debug.md +2 -0
  3. package/bundles/antigravity-plugin/guard_agy.py +6 -2
  4. package/bundles/antigravity-plugin/plugin.json +1 -1
  5. package/bundles/antigravity-plugin/repo_freshness.py +71 -6
  6. package/bundles/antigravity-plugin/repo_hygiene.py +516 -0
  7. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
  8. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
  9. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
  10. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
  11. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
  12. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
  13. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
  14. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
  15. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
  16. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
  17. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
  18. package/bundles/antigravity-plugin/scripts/caddis_checkout_guard.py +1 -1
  19. package/bundles/antigravity-plugin/scripts/caddis_finished.py +537 -0
  20. package/bundles/antigravity-plugin/scripts/caddis_fleet.py +26 -9
  21. package/bundles/antigravity-plugin/scripts/caddis_guide.json +65 -12
  22. package/bundles/antigravity-plugin/scripts/caddis_own_cleanup.py +23 -248
  23. package/bundles/antigravity-plugin/scripts/caddis_preload_review.py +554 -0
  24. package/bundles/antigravity-plugin/scripts/caddis_repo_tidy.py +240 -0
  25. package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +9 -3
  26. package/bundles/antigravity-plugin/scripts/caddis_run.py +160 -0
  27. package/bundles/antigravity-plugin/scripts/caddis_spawn.py +17 -1
  28. package/bundles/antigravity-plugin/scripts/caddis_tidy.py +12 -0
  29. package/bundles/antigravity-plugin/scripts/caddis_upstream_check.py +108 -10
  30. package/bundles/antigravity-plugin/scripts/caddis_worktree_root.py +111 -2
  31. package/bundles/antigravity-plugin/scripts/setup_project_ai.py +132 -11
  32. package/bundles/antigravity-plugin/skills/_registry.md +7 -5
  33. package/bundles/antigravity-plugin/skills/adopt-app/SKILL.md +2 -5
  34. package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md +232 -40
  35. package/bundles/antigravity-plugin/skills/brainstorming/builder-check-prompt.md +25 -0
  36. package/bundles/antigravity-plugin/skills/cloud-phases/SKILL.md +1 -1
  37. package/bundles/antigravity-plugin/skills/dashboard-perf-sweep/SKILL.md +1 -1
  38. package/bundles/antigravity-plugin/skills/db-diagram/SKILL.md +1 -1
  39. package/bundles/antigravity-plugin/skills/explainer-doc/SKILL.md +1 -1
  40. package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +7 -1
  41. package/bundles/antigravity-plugin/skills/fleet-close/SKILL.md +4 -1
  42. package/bundles/antigravity-plugin/skills/graph-email/SKILL.md +15 -0
  43. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +9 -2
  44. package/bundles/antigravity-plugin/skills/implement/SKILL.md +7 -0
  45. package/bundles/antigravity-plugin/skills/particle-art/SKILL.md +1 -3
  46. package/bundles/antigravity-plugin/skills/port-to-github/SKILL.md +2 -5
  47. package/bundles/antigravity-plugin/skills/pr-merge/SKILL.md +1 -1
  48. package/bundles/antigravity-plugin/skills/preload-review/SKILL.md +69 -0
  49. package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +4 -0
  50. package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md +6 -5
  51. package/bundles/antigravity-plugin/skills/ship-merge/SKILL.md +1 -1
  52. package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md +1 -1
  53. package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md +5 -0
  54. package/bundles/antigravity-plugin/skills/tdd/SKILL.md +2 -1
  55. package/bundles/antigravity-plugin/skills/tech-explainer/SKILL.md +2 -6
  56. package/bundles/antigravity-plugin/skills/usage-review/SKILL.md +2 -0
  57. package/bundles/antigravity-plugin/skills/using-git-worktrees/SKILL.md +19 -2
  58. package/bundles/antigravity-plugin/skills/warm-editorial-ui/SKILL.md +1 -1
  59. package/bundles/antigravity-plugin-extras/plugin.json +1 -1
  60. package/bundles/antigravity-plugin-extras/skills/_registry.md +3 -2
  61. package/bundles/antigravity-plugin-extras/skills/building-ai-agent-on-cloudflare/SKILL.md +1 -2
  62. package/bundles/antigravity-plugin-extras/skills/building-mcp-server-on-cloudflare/SKILL.md +1 -2
  63. package/bundles/antigravity-plugin-extras/skills/data-contract-pipeline/SKILL.md +1 -1
  64. package/bundles/antigravity-plugin-extras/skills/graph-email/SKILL.md +53 -0
  65. package/bundles/antigravity-plugin-extras/skills/graph-email/email.toml.example +44 -0
  66. package/bundles/antigravity-plugin-extras/skills/graph-email/scripts/send_email.py +432 -0
  67. package/bundles/antigravity-plugin-extras/skills/responsive-mobile-native/SKILL.md +2 -4
  68. package/bundles/antigravity-plugin-extras/skills/runner-move/SKILL.md +2 -4
  69. package/bundles/antigravity-plugin-extras/skills/setup-project-ai/SKILL.md +1 -1
  70. package/bundles/antigravity-plugin-extras/skills/understand-anything/SKILL.md +2 -5
  71. package/bundles/codex/.codex/skills/coding/dashboard-perf-sweep/SKILL.md +1 -1
  72. package/bundles/codex/.codex/skills/data/db-diagram/SKILL.md +1 -1
  73. package/bundles/codex/.codex/skills/devops/adopt-app/SKILL.md +2 -5
  74. package/bundles/codex/.codex/skills/devops/port-to-github/SKILL.md +2 -5
  75. package/bundles/codex/.codex/skills/devops/using-git-worktrees/SKILL.md +19 -2
  76. package/bundles/codex/.codex/skills/docs/explainer-doc/SKILL.md +1 -1
  77. package/bundles/codex/.codex/skills/docs/tech-explainer/SKILL.md +2 -6
  78. package/bundles/codex/.codex/skills/frontend/warm-editorial-ui/SKILL.md +1 -1
  79. package/bundles/codex/.codex/skills/media/particle-art/SKILL.md +1 -3
  80. package/bundles/codex/.codex/skills/workflow/brainstorming/SKILL.md +232 -40
  81. package/bundles/codex/.codex/skills/workflow/brainstorming/builder-check-prompt.md +25 -0
  82. package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +4 -0
  83. package/bundles/codex/.codex/skills/workflow/roadmap/assets/plan-resume-prompt.md +6 -5
  84. package/bundles/manifest.json +3 -3
  85. package/dist/export/assets/export-CMtV-slT.css +1 -0
  86. package/dist/export/index.html +2 -2
  87. package/dist/ui/assets/{Activity-DZKPMOeV.js → Activity-BDjet2xd.js} +1 -1
  88. package/dist/ui/assets/Guide-Czn5sK0f.js +9 -0
  89. package/dist/ui/assets/Guide-D-Zy4cUT.css +1 -0
  90. package/dist/ui/assets/{RoadmapTab-DPsiSmIF.js → RoadmapTab-Bd8geyQx.js} +1 -1
  91. package/dist/ui/assets/index-Bd0Z4jR8.css +1 -0
  92. package/dist/ui/assets/{index-xl156OCN.js → index-CmngQ8Mk.js} +12 -12
  93. package/dist/ui/index.html +2 -2
  94. package/package.json +1 -1
  95. package/dist/export/assets/export-HxTgj3z2.css +0 -1
  96. package/dist/ui/assets/Guide-5ZFfL6sl.js +0 -9
  97. package/dist/ui/assets/Guide-Dnsb-TRd.css +0 -1
  98. package/dist/ui/assets/index-DGlNAmeA.css +0 -1
  99. /package/dist/export/assets/{export-B7BBDg5I.js → export-DtlDFN4L.js} +0 -0
@@ -1,57 +1,249 @@
1
1
  ---
2
2
  name: brainstorming
3
- description: "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."
3
+ description: "Use before any creative work: new features, components or behavior changes, or planning anything new. Finds what the user wants first."
4
4
  ---
5
5
 
6
- # Brainstorming Ideas Into Designs
6
+ # Brainstorming
7
7
 
8
- ## Overview
8
+ Adapted from obra/superpowers `brainstorming` 7.0.2 (MIT). See NOTICE.md.
9
9
 
10
- Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
10
+ You are very good at building. You build what you believe the user wants. That belief is usually
11
+ thinner than it feels. This skill finds out what the user actually wants, and why, before anything
12
+ gets built.
11
13
 
12
- Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
14
+ People often have not finished working out what they want. Good questions help them think it through.
15
+ When you understand the why, you make the hundred small decisions they never mention the way they
16
+ would have made them.
13
17
 
14
- **Constraint priority order:** (1) always ask one question per message; (2) use multiple choice when options are well-defined; (3) validate incrementally after each design section.
18
+ ## First: what do you actually know?
15
19
 
16
- ## The Process
20
+ Before you reply, ask yourself: what do I know about what the user wants, and why?
17
21
 
18
- **Understanding the idea:**
19
- - Check out the current project state first (files, docs, recent commits)
20
- - Ask questions one at a time to refine the idea
21
- - Prefer multiple choice questions when the options are well-defined and constrained; use open-ended questions when exploring new or unclear ideas
22
- - Only one question per message - if a topic needs more exploration, break it into multiple questions
23
- - Focus on understanding: purpose, constraints, success criteria
22
+ - **Everything that matters is in the request** ("make the icon cornflower blue"). This is a quick,
23
+ clear task. Do it, and say what you did.
24
+ - **Something non-trivial is missing.** Start the conversation.
24
25
 
25
- **Exploring approaches:**
26
- - Propose 2-3 different approaches with trade-offs
27
- - Present options conversationally with your recommendation and reasoning
28
- - Lead with your recommended option and explain why
26
+ Before you start implementing, do these steps in order:
29
27
 
30
- **Presenting the design:**
31
- - Once you believe you understand what you're building, present the design
32
- - Break it into sections of 200-300 words
33
- - Ask after each section whether it looks right so far
34
- - Cover: architecture, components, data flow, error handling, testing
35
- - Be ready to go back and clarify if something doesn't make sense
28
+ 1. Lay out the approaches in a message of their own, and let the user pick one (see "Lay out the
29
+ approaches").
30
+ 2. Write the design doc, short or full (see "Size the work").
31
+ 3. Get the user's approval of that doc.
32
+ 4. Run `/caddis:feature-plan`. It is the only plan writer in caddis. If the superpowers plugin is also
33
+ installed, never use its planning skill: that skips the caddis model routing.
36
34
 
37
- ## After the Design
35
+ If nothing is open when you write your first message and there is one sensible way, steps 1 to 3 happen
36
+ in that message (see "Your first message").
38
37
 
39
- **Documentation:**
40
- - Write the validated design to `.caddis/plans/YYYY-MM-DD-<topic>-design.md`
41
- - Apply `.github/instructions/document-frontmatter.instructions.md` when creating or updating the design doc
42
- - Use elements-of-style:writing-clearly-and-concisely skill if available
43
- - Commit the design document to git
38
+ Two things are not implementing: a spike the user said yes to (see "Spike to feel things out"), and
39
+ doing what they asked once they opted out of the questions.
44
40
 
45
- **Implementation (if continuing):**
46
- - Ask: "Ready to set up for implementation?"
47
- - Use the `using-git-worktrees` skill (caddis, devops/) to create an isolated workspace
48
- - Use `/caddis:feature-plan` to write the plan (it is the only plan writer in caddis)
41
+ ## Look before you ask
49
42
 
50
- ## Key Principles
43
+ In an existing project, or when the user gave you context (a spec, a plan, a handoff, files, earlier
44
+ conversation), dig in before your first message. Read what they referred to and the code or material
45
+ it connects to. Keep reading until you can explain how the relevant parts work today and what this
46
+ change would touch. Never ask what the project or their context already answers. Never reopen what
47
+ they already decided.
51
48
 
52
- - **One question at a time** - Don't overwhelm with multiple questions
53
- - **Multiple choice preferred** - Use when options are well-defined; use open-ended when exploring new or unclear ideas
54
- - **YAGNI ruthlessly** - Remove unnecessary features from all designs
55
- - **Explore alternatives** - Always propose 2-3 approaches before settling
56
- - **Incremental validation** - Present design in sections, validate each
57
- - **Be flexible** - Go back and clarify when something doesn't make sense
49
+ ## Your first message
50
+
51
+ Move the work forward, with one of these:
52
+
53
+ - **They already said what they want** (a spec, a plan, a detailed request). Aim for about 200 words
54
+ for the whole message.
55
+ - Echo the request back in your own words, so they can see whether you got its shape: what they
56
+ want, who it is for, and why, as far as they said.
57
+ - Add what you found that bears on it: how the relevant parts work today and what the change would
58
+ touch. If you found something they may not have considered, such as a constraint, a conflict or a
59
+ cheaper path, say so plainly.
60
+ - How to build it comes later (see "Lay out the approaches").
61
+ - End with one line that invites corrections.
62
+ - If they did not say why they want it, even if you can guess, ask: one open question in their own
63
+ terms, with nothing to pick from.
64
+ - If they told you why, and the request and the project leave open something that would change what
65
+ gets built, ask about the one that changes it most. When the choices can be named, sketch each one
66
+ concretely, with what it trades off and which you would pick.
67
+ - If nothing like that is open, there is one sensible way. End with the short design itself (the
68
+ approach, a line on why the others do not fit, and the design in a few lines) and ask them to
69
+ approve it. Their approval covers the approach and the design. Write the short design doc as
70
+ approved and go on to the plan.
71
+ - Specs are often incomplete, so confirm before you build on one.
72
+ - **They did not:** ask one open question, in their own terms, about the biggest thing the request
73
+ leaves unsettled. Say why you ask: what the answer would change about what you build. For "a website
74
+ for my bakery": "If it is mostly for people deciding whether to stop by, I would lead with hours and
75
+ what is in the case today. Taking orders is a different site. What do you want someone to do when
76
+ they land on it?"
77
+
78
+ How the message ends depends on whether the user asked for brainstorming:
79
+
80
+ - **They asked for it** (by name, by invoking it, or by asking for a design discussion): end there.
81
+ They want this conversation.
82
+ - **They did not:** they may not want a conversation at all. End with a light, one-line offer to just
83
+ get going, such as "Or if you would rather I just dive in, say so." If they take it, this skill is
84
+ done. State any significant how-it-gets-made choice (platform, language, medium) in one plain line.
85
+ Then do what they asked through the normal workflow.
86
+
87
+ That is the whole message.
88
+
89
+ ## The conversation
90
+
91
+ Ask a question only when the answer would change what gets built and neither the request nor the
92
+ project answers it. Otherwise, state your call and your reason as a proposal the user can correct, and
93
+ move the work forward. Process steps are always your calls: writing things up, where files go, looking
94
+ further, how to show something. Do them and say so. Ask one question at a time. Use plain language,
95
+ pitched a little above where the user is. Match their vocabulary. Do not use process jargon. Never
96
+ quote this skill to the user.
97
+
98
+ Be clear and short. Lead with what matters. When you report what you found, give the most important
99
+ findings and offer the rest.
100
+
101
+ **Get them describing.** Until you know why they want it, ask open questions, with no example answers
102
+ attached. Their own words carry intent that your options cannot. Once you know why, and a decision has
103
+ choices you can name, sketch each one concretely, with what it trades off and which you would pick.
104
+ When they say "just guess" or "what do you think?", propose something concrete.
105
+
106
+ **How it gets made.** Every project rests on choices about medium, tools, materials and resources: the
107
+ platform, language and libraries for an app; the medium for a piece of art. Read from how they talk
108
+ which choices they want to make. A user who raises the how, or asks about trade-offs, wants the options
109
+ with your pick. A user who talks about outcomes hands you the how: make those calls and state each in
110
+ one line. When work already exists, build on what it uses. Any choice you make goes in the design as
111
+ your call, never as something the user agreed to.
112
+
113
+ **Ground to cover.** This is territory, not a script. Never read it out as questions:
114
+
115
+ - what kind of thing this is, and what makes it special
116
+ - why now, and what success looks like to the user
117
+ - goals, non-goals and anti-goals (what would make this a failure even if it technically works)
118
+ - prior art: what they have seen elsewhere, loved or hated
119
+ - current state: what exists now, what they have tried
120
+ - the details they care about
121
+
122
+ **Make every question specific** to their project and what they told you. Ask Socratically, as a sharp
123
+ colleague would. Build each question on their last answer or on something you found, so it helps them
124
+ think through a consequence or a case they may have missed ("Voting closes before the meeting, and two
125
+ members joined this month. Does someone who joins mid-round get a vote?"). When the reason is not
126
+ plain, say what you hope to learn or what the answer would change. A proposal they can correct, with
127
+ your reason, often beats a question.
128
+
129
+ **Do recon.** When you have some grounding and looking further would help, go look: deeper into the
130
+ codebase or project, the user's own files and data, or the web. Say what you looked for and what you
131
+ found.
132
+
133
+ **Lay out the approaches.** When you understand what they want, and before you write anything up, put
134
+ the ways of building it in a message of its own.
135
+
136
+ - Come up with several real alternatives. Drop the weak ones, including any that work against why they
137
+ want it and any that the existing work rules out.
138
+ - Sketch the two or three that remain, concretely enough to picture, grounded in what the project
139
+ actually does, with what each trades off.
140
+ - Recommend one and say why. Then ask which way they want to go. If they handed you the how, say you
141
+ will go with your pick instead.
142
+ - When there is genuinely one sensible way, say so in that message and explain why the others do not
143
+ fit. The design comes in the next message.
144
+
145
+ This is for how it gets built. For what they want, get them describing first.
146
+
147
+ **Show, do not tell.** When seeing would help more than reading, sketch it in text: a few lines of what
148
+ they would see. When the look itself is theirs to decide (a screen, a page, a layout, a flow, options
149
+ that look different from each other), offer a mockup through the `mockup` skill or an HTML artifact.
150
+ Offer it once, as its own short message. If the user declines, stay in text.
151
+
152
+ **Spike to feel things out.** Agentic work is waterfall, but very fast. A quick throwaway build is
153
+ often the cheapest way to learn what the user wants or whether something works. Offer one when it
154
+ would help. When the user just wants to spike, get out of the way. A spike gets no tests or minimal
155
+ ones, is not bulletproof, and skips the plan, implementation and review steps. Bring what the spike
156
+ taught you back into the conversation.
157
+
158
+ ## Play it back
159
+
160
+ Play back as you go. When you understand one part well enough to describe it (what it is for and who
161
+ it serves, or how one piece behaves), describe that part back in about 200-300 words. Then return to
162
+ questions about the next part. Playback and questions alternate through the whole conversation. The
163
+ last chunk covers whatever is left.
164
+
165
+ Only what the user said goes in as theirs. Anything you filled in goes in as your proposal, with your
166
+ reason. End each chunk by asking what is wrong or missing.
167
+
168
+ Before you send a chunk, check it: does it describe something they will look at, such as a page, a
169
+ screen, a schedule or a printout? If so, put a text sketch next to the description. If the look is
170
+ theirs to decide and they have not seen the mockup offer yet, send the offer instead, as its own
171
+ message, and hold the chunk for the next message.
172
+
173
+ ## Size the work
174
+
175
+ When you understand what the user wants and they picked an approach, say how big the work is, in plain
176
+ words. The user can override it.
177
+
178
+ | Size | The design doc |
179
+ |------|----------------|
180
+ | A small change | a short one: what you already covered together, written down |
181
+ | A project | the full written design (below) |
182
+
183
+ Short or full, the design doc has an **Approaches** part: the two or three ways you considered, what
184
+ each trades off, which one the user picked, and why. They pick in the conversation, before you write
185
+ the doc.
186
+
187
+ If the work grows mid-task, stop, say so, and step up a size.
188
+
189
+ If this is really several independent projects, say so, agree on an order, and brainstorm them one at
190
+ a time.
191
+
192
+ ## The written design
193
+
194
+ Write a plain document that a talented builder in the domain could plan from, without going back to the
195
+ user. Cover:
196
+
197
+ - intent and the why
198
+ - goals, non-goals, anti-goals
199
+ - constraints
200
+ - approaches (above)
201
+ - the parts of the how the user decided, as they decided them
202
+ - what is left to the builder
203
+
204
+ For a small change, the short design covers the same points in a line or two each. It goes straight to
205
+ the user, without the builder check.
206
+
207
+ **Where it goes:** `.caddis/plans/YYYY-MM-DD-<topic>-design.md`, committed. Apply
208
+ `.github/instructions/document-frontmatter.instructions.md` when the repo has it. Outside a repo, pick
209
+ a sensible place and say where. The user's preference overrides both.
210
+
211
+ **Builder check** (for a project): dispatch a fresh subagent with `builder-check-prompt.md` in this
212
+ folder. When you tell the user you are writing it up, say that a reviewer will read it first and you
213
+ may come back once with a few questions. Do not hand over the document until the check is back. Sort
214
+ what the builder asks into three piles:
215
+
216
+ - **Answered already** by the conversation or the project: put the answer in the document.
217
+ - **Minor:** a sensible builder could settle it without changing what gets built. Settle it yourself
218
+ and mark it in the document as your call.
219
+ - **Theirs:** only the user can answer it, and the answer changes what gets built.
220
+
221
+ Bring the "theirs" pile in one message, most important first. Update the document with the answers.
222
+ Then hand it over with a short list of the calls you made, so the user can check them while reading.
223
+ That is the only round of questions the check produces. Without a subagent tool, read the document as
224
+ that builder yourself.
225
+
226
+ <HARD-GATE>
227
+ Nothing gets built until the user approves the design doc: the short one for a small change, the full
228
+ one for a project. Building includes writing product code, scaffolding, installing dependencies,
229
+ creating projects and invoking an implementation skill. Reading and exploring are fine.
230
+
231
+ Two exceptions. If the user opted out of the questions, the skill is done and the gate goes with it.
232
+ A spike the user said yes to may be built. It stays labeled throwaway. Keeping what it produced is a
233
+ new request that comes back through this gate.
234
+
235
+ After the design doc is approved, the next step is the plan: run `/caddis:feature-plan` and no other
236
+ planning skill. Isolate the work with the `using-git-worktrees` skill when the checkout is not safe to
237
+ move.
238
+ </HARD-GATE>
239
+
240
+ ## Red flags
241
+
242
+ | Thought | Reality |
243
+ |---------|---------|
244
+ | "I'll offer a menu of what they might want" | Options steer. Ask them to describe it first. |
245
+ | "I'll fill in sensible defaults" | Good. Say them out loud. A default the user never heard is one they could not reject. |
246
+ | "I answered their questions, so I'll write the doc" | Lay out the approaches first, in a message of their own (or, when nothing was open from the start, in the short design in your first message). |
247
+ | "I should explain the process first" | Ask your question. The process shows itself. |
248
+ | "They said 'sounds good' to the idea" | Approval covers what you showed them. A design doc you have not written is not approved. |
249
+ | "The spike works, I'll keep building on it" | Keeping it is a new request. Back through the gate. |
@@ -0,0 +1,25 @@
1
+ # Builder Check Prompt
2
+
3
+ Adapted from obra/superpowers `brainstorming` 7.0.2 (MIT). See NOTICE.md.
4
+
5
+ Dispatch a fresh subagent with this prompt once the written design exists. Fill in the domain and the
6
+ document path. Use Sonnet for the builder subagent.
7
+
8
+ ```
9
+ You are a talented [DOMAIN, e.g. "software engineer", "event planner",
10
+ "bakery consultant"]. You have been handed a design document and asked to
11
+ put together a plan to build what it describes. You cannot talk to the
12
+ person who wrote it.
13
+
14
+ Read [DOCUMENT_PATH].
15
+
16
+ Report only the questions you would still need answered before you could
17
+ plan this well: places where you would have to guess and a wrong guess
18
+ would matter. For each, give the question and why the answer changes the
19
+ plan. Rank them by importance.
20
+
21
+ Skip anything the document explicitly leaves to the builder, and anything
22
+ you could reasonably decide yourself. Skip nitpicks about wording.
23
+
24
+ If nothing important is left, say "nothing important left".
25
+ ```
@@ -41,7 +41,7 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
41
41
  `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
42
42
  - **Pull a branch to test it:** `git fetch origin`, then
43
43
  `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name> --record --purpose "test <name>")" origin/<branch>` (for the default branch,
44
- `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
44
+ `origin/<default>`), and run the gates there. Install dependencies fresh with `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" --bootstrap` (run in the worktree); never link `node_modules` or a venv.
45
45
  - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
46
46
  `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
47
47
  checkout has the default branch out; then leave it and report it. Delete the local feature branch only when no
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: dashboard-perf-sweep
3
3
  context: fork
4
- description: 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.
4
+ description: Re-measure dashboard/API endpoints for load-time regressions. Use when the user says "sweep dashboard performance", "check if this app needs rs-kit", or "re-measure the perf tracker".
5
5
  ---
6
6
 
7
7
  # dashboard-perf-sweep — re-measure, then judge the shape, not just the time
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: db-diagram
3
3
  context: fork
4
- description: 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.
4
+ description: Diagram SQL artifacts (procs, views, queries, tables) as Mermaid or Excalidraw. Use when the user says "diagram this SQL", "draw the ER diagram", "/mermaid-db", or "/excalidraw-db".
5
5
  ---
6
6
 
7
7
  # db-diagram — explain SQL as a diagram
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: explainer-doc
3
3
  context: fork
4
- description: 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.
4
+ description: Write a self-contained hand-off spec for an external team or vendor. Use when the user says "write a spec for the X team", "explainer doc", "spec for a vendor", or "hand this off to Y".
5
5
  ---
6
6
 
7
7
  # explainer-doc — write for the reader who has no other context
@@ -345,10 +345,16 @@ yourself (relay + Tracker) before stopping — do not hand back "run `/caddis:ha
345
345
  <same structure>
346
346
 
347
347
  ## Execution protocol (standing rules — this plan is the memory, not anyone's head)
348
+ Script commands in the plan text (these rules, task commands, exit gates) are written
349
+ `python "<home>/.caddis/bin/caddis_run.py" <script> ...` (`<home>` is the user's home folder, forward
350
+ slashes), never the expanded plugin path: a later session runs them after an update, when a versioned
351
+ `.../caddis/caddis/<version>/` folder is gone. The one exception is a Lane launch line, which
352
+ `caddis_gate.py lane-check` validates in its own form (above).
353
+
348
354
  Three rules: one attempt, one review.
349
355
  1. **Think before you send.** Before a task goes to any coder, write its edge cases and check the facts it depends on (one query or one file read).
350
356
  2. **Run it before review.** The coder runs only the tests of the files it touched, in the foreground, each command under 10 minutes (split into parts if needed). Name the exact commands in the task. Never start the full suite in the background and never wait on a monitor for it: CI runs the full suite on every PR. Then run the change once on real data.
351
- 3. **Review by tier.** Run `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_gate.py" review-tier --range <base>...HEAD` (add `--plan <plan> --phase <N>` inside a plan; no `TIER:` line means tier 2).
357
+ 3. **Review by tier.** Run `python "<home>/.caddis/bin/caddis_run.py" caddis_gate.py review-tier --range <base>...HEAD` (add `--plan <plan> --phase <N>` inside a plan; no `TIER:` line means tier 2).
352
358
  Tier 0: gates only. Tier 1-small: your self-check only. Tier 1: one review by another vendor; stop at
353
359
  the first CLEAN. Tier 2: one review by another vendor (two only when the owner asks). Fix blocking findings only;
354
360
  park the rest. Re-review only the fix diff, and only when the fix changed logic. After 3 rounds, ask the owner.
@@ -83,7 +83,10 @@ Then these close rules, in the message:
83
83
  the action after the stop).
84
84
  4. Your resume prompt must load your tasks file, greet peers with `<role> is now <your new name>`, and,
85
85
  in a shared checkout, say: "read code facts from origin/main; a worktree needs its own fresh
86
- dependencies".
86
+ dependencies". A script command in the prompt is written
87
+ `python "<home>/.caddis/bin/caddis_run.py" <script> ...` (`<home>` is your home folder, forward
88
+ slashes), never the expanded plugin path: the sheet is read after the next update, when a versioned
89
+ `.../caddis/caddis/<version>/` folder is gone. `ack add` refuses a prompt that holds one.
87
90
  5. Reply to `<coordinator>` with this block (one line, every field filled), then your full resume prompt:
88
91
  ```
89
92
  FLEET-ACK name=<n> role=<r> machine=<m> folder=<abs> relay=<path> tasks=<path|none> mode=<new|keeps-running|restore-on:<machine>|nothing> owns-watchers=<yes|no> worktrees=<abs;abs|none>
@@ -0,0 +1,15 @@
1
+ ---
2
+ name: graph-email
3
+ description: Send a Markdown file as an email through Microsoft Graph or SMTP, as set in ~/.caddis/email.toml. Default recipient is the owner.
4
+ ---
5
+
6
+ Use the `graph-email` skill to send an email.
7
+
8
+ Arguments: $ARGUMENTS
9
+
10
+ 1. Read the skill `graph-email` first and follow it.
11
+ 2. If `~/.caddis/email.toml` is missing, or `--check` fails, tell the owner what is missing and stop. Do not guess values.
12
+ 3. The first argument is the Markdown file. If there is none, ask which file, or offer to write one in the project's `comms/` folder.
13
+ 4. Subject: `caddis-<app-name> <subject>`. Take the app name from the project folder. If the owner gave subject words, use them.
14
+ 5. Recipient: the owner's own address unless `--to` is given. If `--to` is any other address, confirm with the owner before sending.
15
+ 6. Run a dry run, check the preview, then send. Report the provider, status, recipient and subject. Keep a copy of the file in `comms/`.
@@ -303,6 +303,7 @@ Read .caddis/relay/<name>.md, then the plan it points to. Continue from <phase/s
303
303
  Load every row of .caddis/relay/<name>.tasks.md with TaskCreate.
304
304
  \`\`\`
305
305
  (Keep the `Load every row` sentence only when Step 3c wrote `.caddis/relay/<name>.tasks.md`.)
306
+ (A script command in the prompt is written `python "<home>/.caddis/bin/caddis_run.py" <script> ...`, never the expanded plugin path: see Rules.)
306
307
 
307
308
  STATUS: <CONTINUE | OWNER-GATE <P>-OG<n> | BLOCKED <owner> | FAILED <reason>>
308
309
  ```
@@ -526,8 +527,9 @@ The `cd` makes the relay's repo-relative paths work from any terminal folder (`;
526
527
  the new session to run `caddis_fleet.py whoami` with its new name, then `caddis_fleet.py peers`, and to send
527
528
  each named live peer in the same repo (the checkout and its worktrees) one `SendMessage`:
528
529
  `<name> started in <folder>: <next action>. No reply needed.` The fenced block stays the relay's text. A
529
- session that pastes the block, not the start line, announces nothing. The script path is written out in the
530
- sentence, because a new session cannot expand `${CLAUDE_PLUGIN_ROOT}`.
530
+ session that pastes the block, not the start line, announces nothing. The sentence names the stable launcher
531
+ (`~/.caddis/bin/caddis_run.py`), because a new session cannot expand `${CLAUDE_PLUGIN_ROOT}` and a versioned
532
+ plugin path is gone after the next update.
531
533
  - **Fleet close.** When this handoff runs because a peer sent `FLEET CLOSE from <coordinator>`, add
532
534
  `--fleet`. The Start line is then `Start line: from the restart sheet`: the restart sheet is the only
533
535
  start line in a fleet close, and `/caddis:fleet-open` already greets the peers, so it has no announce
@@ -538,6 +540,11 @@ The `cd` makes the relay's repo-relative paths work from any terminal folder (`;
538
540
  `--role <role>` to set another.
539
541
 
540
542
  ## Rules
543
+ - **Script commands in persisted text.** In text a later session reads (the relay, its `## Resume prompt`, the
544
+ tasks file), write `python "<home>/.caddis/bin/caddis_run.py" <script> ...` (`<home>` is the user's home folder, forward slashes), never the
545
+ expanded plugin path. An expanded `${CLAUDE_PLUGIN_ROOT}` holds the plugin version and is gone after the next update.
546
+ `${CLAUDE_PLUGIN_ROOT}` stays right in a command that runs now. `caddis_fleet.py resume-block` refuses a prompt that holds a
547
+ versioned path.
541
548
  - **Context rule.** Above 200k: checkpoint at the next card end when 2 or more cards are left; else finish
542
549
  the phase and run the full handoff. At 280k: checkpoint at the first moment no agent or background command
543
550
  runs. Then ask the owner for `/clear`. Each turn re-reads the whole conversation, so a long session costs
@@ -91,6 +91,10 @@ and 95-154 turns per session were started by background events. Each turn re-rea
91
91
  `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spend.py" run --caller lane-pN -- agy ...`.
92
92
  - **Fewer wake-ups.** Run one `ci-watch` per PR head. When it times out on a queued run, watch that run once
93
93
  with `ci-watch --run <id>`; do not start a new PR watch. Write no "still waiting" turns.
94
+ - **Silent agents.** For a subagent in its own worktree, start the shell watcher in the background (a script, not a
95
+ model): `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_silence_watch.py" --worktree <path> --silent-min 20`. Exit 3
96
+ and a `SILENT:` line mean no commit, file change or output for 20 minutes. Then look at the agent, and stop or
97
+ resume it. Add `--extra-file <the agent's output file>` so a long quiet build does not count as silence.
94
98
 
95
99
  ## Waves
96
100
 
@@ -340,6 +344,9 @@ report — do not redo completed work.
340
344
  result) under `## Task progress` in the review file. Then run the phase's normal gates: VERIFY,
341
345
  the ONE `review-tier` review by one other vendor at the end of the phase, COMMIT and the Tracker.
342
346
  Re-check a fix only when it fixes a blocking finding and changes logic.
347
+ After an auto-compact, re-read this EXECUTION item and `## Task progress` before the next task. Do not
348
+ trust your memory of the rules. Resume at the first task with no entry there (adapted from superpowers
349
+ 7.0.2 `subagent-driven-development`).
343
350
  - **RED** — write the failing test(s) the phase names (`<test file>::<case>`). Run them; confirm they
344
351
  fail for the right reason (the missing behavior, not an import error). If a phase genuinely has no
345
352
  testable surface, say so in the review file and implement the minimal change directly.
@@ -4,9 +4,7 @@ version: 1.0.0
4
4
  description: >-
5
5
  Zero-dependency animated particle art as a React/Next.js component (spring physics, CSS-variable
6
6
  theming, mouse interaction). Use for animated hero art or a living logo, or on "particle animation",
7
- "particles that form a shape", "animated letter/logo/initials", "morphing particles",
8
- "constellation", "neural net art", "halftone animation", "ASCII art animation", or "art that reacts
9
- to mouse".
7
+ "animated letter/logo/initials" or "morphing particles".
10
8
  ---
11
9
 
12
10
  # Particle Art Generator
@@ -1,11 +1,8 @@
1
1
  ---
2
2
  name: port-to-github
3
3
  description: >-
4
- Port an app or repo to GitHub from any source (git server, local folder, UNC share, Windows box over
5
- WinRM): all branches and tags, SHA-verified, CI translated, source-only history, deploy cut over
6
- with rollback. Use when the user says "move this app to GitHub", "port X to GitHub", "migrate from
7
- Gitea", "this app only exists on the server", "import the repo from the prod box", "keep binaries
8
- out of the repo", or "cut the deploy over to GitHub".
4
+ Port an app or repo to GitHub with verified history, CI translation, and deploy cutover. Use when
5
+ the user says "move this app to GitHub", "port X to GitHub", or "migrate from Gitea".
9
6
  ---
10
7
 
11
8
  # port-to-github
@@ -47,7 +47,7 @@ It prints `SHARED: yes <reason>` or `SHARED: no` and exits 0. It says yes when t
47
47
  `git -C <worktree> rebase origin/<default>` and `git -C <worktree> push --force-with-lease origin HEAD:<branch>`.
48
48
  - **Pull a branch to test it:** `git fetch origin`, then
49
49
  `git worktree add --detach "$(python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" test-<name> --record --purpose "test <name>")" origin/<branch>` (for the default branch,
50
- `origin/<default>`), and run the gates there. Install dependencies fresh; never link `node_modules` or a venv.
50
+ `origin/<default>`), and run the gates there. Install dependencies fresh with `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_worktree_root.py" --bootstrap` (run in the worktree); never link `node_modules` or a venv.
51
51
  - **Clean up after a merge:** do not switch or pull. Run `git fetch --prune`, then
52
52
  `git fetch origin <default>:<default>`: it fast-forwards the default branch with no checkout. Git refuses when a
53
53
  checkout has the default branch out; then leave it and report it. Delete the local feature branch only when no
@@ -0,0 +1,69 @@
1
+ ---
2
+ name: preload-review
3
+ description: Show what loads before the first prompt in every repo (rules, memory index, skills, MCP names) and list what to shorten
4
+ ---
5
+
6
+ # /preload-review — what loads before the first prompt
7
+
8
+ Measure the size of what Claude loads before you type anything: your user rules, the enabled
9
+ skills, the MCP server names, and, for every repo under a root folder, the repo rules and the
10
+ memory index. The command reads files only. It shows estimates (characters divided by 4), not exact
11
+ token counts. It changes nothing unless you say yes.
12
+
13
+ ## Step 1 — find the script
14
+
15
+ Resolve the script path:
16
+ - Plugin install: `${CLAUDE_PLUGIN_ROOT}/scripts/caddis_preload_review.py`
17
+ - harness (caddis) checkout: `scripts/caddis_preload_review.py`
18
+
19
+ ## Step 2 — run it
20
+
21
+ Run it from the project root:
22
+ ```
23
+ python "<resolved-path>" $ARGUMENTS
24
+ ```
25
+
26
+ - With no flags, the root folder is the parent of the current git repo. Pass `--root PATH` to scan
27
+ another folder.
28
+ - The script prints Markdown to stdout. It also has `--json`, `--limit-repo-startup N` and
29
+ `--limit-memory N`.
30
+ - The script exits 0 always. Cut candidates are advice, not a failure.
31
+
32
+ ## Step 3 — show the output
33
+
34
+ Show the Markdown output as it is. Then add **one sentence** that names the largest start-up cost
35
+ (a repo, the skills or the user rules). Do not repeat every row in prose: the table is the output.
36
+
37
+ ## Step 4 — point to /context
38
+
39
+ Tell the user to run `/context` once in a session. The script cannot see the exact MCP tool lists,
40
+ or skills that do not come from the plugin cache. Compare the `/context` output with the table.
41
+
42
+ ## Step 5 — offer actions only
43
+
44
+ For each cut candidate, say the one action it names (run `caddis:claude-md-curator`, shorten the
45
+ memory index lines, move how-to text into a doc that loads on demand, or turn a plugin off).
46
+
47
+ **Never edit a rules file, a memory file or a setting without the owner's yes.** Show the change
48
+ first. Then ask.
49
+
50
+ ## Step 6 — record the review
51
+
52
+ After the owner has read the report, run the script again with `--stamp`:
53
+ ```
54
+ python "<resolved-path>" [--root PATH] --stamp
55
+ ```
56
+
57
+ This writes `.caddis/.last-preload-review` for the current repo: the review date and a hash of the
58
+ enabled plugin set. Then say that the stamp is written.
59
+
60
+ ## Notes
61
+
62
+ - The stamp file is local and gitignored. It is the only file the script ever writes. Without
63
+ `--stamp` the script writes nothing.
64
+ - The SessionStart hook reads the stamp. It prints one line when the last review is more than
65
+ 30 days old, or when the enabled plugins changed since then. It prints nothing when both are fresh.
66
+ - The script prints only names from `~/.claude.json` and `~/.claude/settings.json`. It never
67
+ prints a value, a URL, an argument or an env var from them.
68
+ - Nested `CLAUDE.md` and `AGENTS.md` files load only when Claude works in that folder. The report
69
+ lists them apart and never adds them to the start-up total.
@@ -12,6 +12,10 @@ by `caddis_merge_chain.py --docs-only`; a repo that wants a human to review them
12
12
  `scripts/` below is the caddis scripts folder: `${CLAUDE_PLUGIN_ROOT}/scripts` in an installed plugin, `scripts/` in
13
13
  the caddis source repo.
14
14
 
15
+ In text that a later session reads (a roadmap row's check command, a restart prompt, a relay), write a script command as
16
+ `python "<home>/.caddis/bin/caddis_run.py" <script> ...` (`<home>` is the user's home folder, forward slashes), never the
17
+ expanded plugin path: it holds the plugin version and is gone after the next update. The runner's own prompt does this.
18
+
15
19
  ## The folder
16
20
 
17
21
  `.caddis/roadmaps/<slug>/` holds:
@@ -8,8 +8,9 @@ timestamp: {{date}}
8
8
 
9
9
  You are a fresh session for the plan `{{slug}}`. Do ONE batch, then stop.
10
10
 
11
- In the commands below, `<scripts>` is the caddis scripts folder `{{scripts}}` (put it in quotes if it holds a space).
12
- Use the scripts in that folder; do not look for them in another caddis install.
11
+ To run a caddis script, write `{{run}} <script.py> <args>`. The launcher finds the installed caddis plugin by itself.
12
+ Do not look for the scripts in a plugin cache folder, and do not write such a path in the relay: it holds the plugin
13
+ version and is gone after the next update.
13
14
 
14
15
  ## 1. Read
15
16
 
@@ -44,7 +45,7 @@ publish a branch that does). Commit the phase there, with its tracker row set to
44
45
  ## 4. Work
45
46
 
46
47
  - Do ONE batch with `/caddis:implement` discipline: tests first, the phase's exit gate, a commit per phase.
47
- - agy sessions only: run `python {{scripts}}/caddis_spend.py check` before each agy call. There is no spend cap (it
48
+ - agy sessions only: run `{{run}} caddis_spend.py check` before each agy call. There is no spend cap (it
48
49
  always exits 0); if its line ends with ` - ADVISORY`, say so in the relay for the owner.
49
50
  - You may do everything except pass an owner gate. Never pass an owner gate. Never raise a cap. Never delete a STOP file.
50
51
  - The runner reviews `risk: high` phases. A phase marked `**Risk:** high`: do not halt for it and do not run the
@@ -55,8 +56,8 @@ publish a branch that does). Commit the phase there, with its tracker row set to
55
56
 
56
57
  ## 5. Write the relay
57
58
 
58
- Write the relay with `python <scripts>/caddis_workstreams.py put --require-status {{slug}} <file>`. Write `<file>` outside
59
- the repo (for example in the temp folder). Read the current relay first with `python <scripts>/caddis_workstreams.py read {{slug}}`;
59
+ Write the relay with `{{run}} caddis_workstreams.py put --require-status {{slug}} <file>`. Write `<file>` outside
60
+ the repo (for example in the temp folder). Read the current relay first with `{{run}} caddis_workstreams.py read {{slug}}`;
60
61
  keep its frontmatter shape (`type: relay`, `workstream: {{slug}}`, `branch`, `session_id`, `plan`, `generated.at`). The LAST
61
62
  non-empty line must be exactly one of these four:
62
63