@caddis/cli 0.4.92 → 0.4.93
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -0
- package/bundles/antigravity-plugin/agents/debug.md +2 -0
- package/bundles/antigravity-plugin/plugin.json +1 -1
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
- package/bundles/antigravity-plugin/scripts/caddis_checkout_guard.py +1 -1
- package/bundles/antigravity-plugin/scripts/caddis_fleet.py +26 -9
- package/bundles/antigravity-plugin/scripts/caddis_guide.json +58 -6
- package/bundles/antigravity-plugin/scripts/caddis_preload_review.py +554 -0
- package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +9 -3
- package/bundles/antigravity-plugin/scripts/caddis_run.py +160 -0
- package/bundles/antigravity-plugin/scripts/caddis_spawn.py +17 -1
- package/bundles/antigravity-plugin/scripts/caddis_upstream_check.py +108 -10
- package/bundles/antigravity-plugin/scripts/setup_project_ai.py +65 -1
- package/bundles/antigravity-plugin/skills/_registry.md +3 -1
- package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md +232 -40
- package/bundles/antigravity-plugin/skills/brainstorming/builder-check-prompt.md +25 -0
- package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +7 -1
- package/bundles/antigravity-plugin/skills/fleet-close/SKILL.md +4 -1
- package/bundles/antigravity-plugin/skills/graph-email/SKILL.md +15 -0
- package/bundles/antigravity-plugin/skills/handoff/SKILL.md +9 -2
- package/bundles/antigravity-plugin/skills/implement/SKILL.md +3 -0
- package/bundles/antigravity-plugin/skills/particle-art/SKILL.md +1 -3
- package/bundles/antigravity-plugin/skills/preload-review/SKILL.md +69 -0
- package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +4 -0
- package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md +6 -5
- package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md +5 -0
- package/bundles/antigravity-plugin/skills/tdd/SKILL.md +2 -1
- package/bundles/antigravity-plugin/skills/usage-review/SKILL.md +2 -0
- package/bundles/antigravity-plugin-extras/plugin.json +1 -1
- package/bundles/antigravity-plugin-extras/skills/_registry.md +1 -0
- package/bundles/antigravity-plugin-extras/skills/graph-email/SKILL.md +53 -0
- package/bundles/antigravity-plugin-extras/skills/graph-email/email.toml.example +44 -0
- package/bundles/antigravity-plugin-extras/skills/graph-email/scripts/send_email.py +432 -0
- package/bundles/codex/.codex/skills/media/particle-art/SKILL.md +1 -3
- package/bundles/codex/.codex/skills/workflow/brainstorming/SKILL.md +232 -40
- package/bundles/codex/.codex/skills/workflow/brainstorming/builder-check-prompt.md +25 -0
- package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +4 -0
- package/bundles/codex/.codex/skills/workflow/roadmap/assets/plan-resume-prompt.md +6 -5
- package/bundles/manifest.json +3 -3
- package/dist/export/assets/export-CMtV-slT.css +1 -0
- package/dist/export/index.html +2 -2
- package/dist/ui/assets/{Activity-DZKPMOeV.js → Activity-BDjet2xd.js} +1 -1
- package/dist/ui/assets/Guide-Czn5sK0f.js +9 -0
- package/dist/ui/assets/Guide-D-Zy4cUT.css +1 -0
- package/dist/ui/assets/{RoadmapTab-DPsiSmIF.js → RoadmapTab-Bd8geyQx.js} +1 -1
- package/dist/ui/assets/index-Bd0Z4jR8.css +1 -0
- package/dist/ui/assets/{index-xl156OCN.js → index-CmngQ8Mk.js} +12 -12
- package/dist/ui/index.html +2 -2
- package/package.json +1 -1
- package/dist/export/assets/export-HxTgj3z2.css +0 -1
- package/dist/ui/assets/Guide-5ZFfL6sl.js +0 -9
- package/dist/ui/assets/Guide-Dnsb-TRd.css +0 -1
- package/dist/ui/assets/index-DGlNAmeA.css +0 -1
- /package/dist/export/assets/{export-B7BBDg5I.js → export-DtlDFN4L.js} +0 -0
|
@@ -1,57 +1,249 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: brainstorming
|
|
3
|
-
description: "
|
|
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
|
|
6
|
+
# Brainstorming
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Adapted from obra/superpowers `brainstorming` 7.0.2 (MIT). See NOTICE.md.
|
|
9
9
|
|
|
10
|
-
|
|
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
|
-
|
|
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
|
-
|
|
18
|
+
## First: what do you actually know?
|
|
15
19
|
|
|
16
|
-
|
|
20
|
+
Before you reply, ask yourself: what do I know about what the user wants, and why?
|
|
17
21
|
|
|
18
|
-
**
|
|
19
|
-
|
|
20
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
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
|
-
|
|
40
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
- **
|
|
57
|
-
|
|
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
|
+
```
|
|
@@ -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 "
|
|
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
|
|
530
|
-
|
|
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
|
|
@@ -340,6 +340,9 @@ report — do not redo completed work.
|
|
|
340
340
|
result) under `## Task progress` in the review file. Then run the phase's normal gates: VERIFY,
|
|
341
341
|
the ONE `review-tier` review by one other vendor at the end of the phase, COMMIT and the Tracker.
|
|
342
342
|
Re-check a fix only when it fixes a blocking finding and changes logic.
|
|
343
|
+
After an auto-compact, re-read this EXECUTION item and `## Task progress` before the next task. Do not
|
|
344
|
+
trust your memory of the rules. Resume at the first task with no entry there (adapted from superpowers
|
|
345
|
+
7.0.2 `subagent-driven-development`).
|
|
343
346
|
- **RED** — write the failing test(s) the phase names (`<test file>::<case>`). Run them; confirm they
|
|
344
347
|
fail for the right reason (the missing behavior, not an import error). If a phase genuinely has no
|
|
345
348
|
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
|
-
"
|
|
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
|
|
@@ -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
|
-
|
|
12
|
-
|
|
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 `
|
|
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 `
|
|
59
|
-
the repo (for example in the temp folder). Read the current relay first with `
|
|
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
|
|
|
@@ -166,6 +166,11 @@ Then add the four things the inventory cannot derive:
|
|
|
166
166
|
**Nothing may be written from recall.** Every number comes from a command run during this capture,
|
|
167
167
|
or from a file quoted by path.
|
|
168
168
|
|
|
169
|
+
**Script commands.** The successor reads this handover after an update, so write a script command as
|
|
170
|
+
`python "<home>/.caddis/bin/caddis_run.py" <script> ...` (`<home>` is the user's home folder, forward
|
|
171
|
+
slashes), never the expanded plugin path (`${CLAUDE_PLUGIN_ROOT}` holds the plugin version).
|
|
172
|
+
`caddis_spawn.py check` refuses a versioned path.
|
|
173
|
+
|
|
169
174
|
### Then check what you wrote
|
|
170
175
|
|
|
171
176
|
```bash
|
|
@@ -29,7 +29,8 @@ test. Show it green.
|
|
|
29
29
|
layer, dispatch the **tester** subagent.
|
|
30
30
|
|
|
31
31
|
## Rules
|
|
32
|
-
-
|
|
32
|
+
- **Iron Law:** no production code without a failing test first. Code written before its test is deleted,
|
|
33
|
+
not adapted or kept as reference. The `tdd-workflow` skill has the rationalizations and red flags.
|
|
33
34
|
- Test behavior, not internals. Assert what a caller observes.
|
|
34
35
|
- Each test independent; shared setup in fixtures.
|
|
35
36
|
- Show real command output at RED and GREEN — don't claim a state you didn't run.
|
|
@@ -41,6 +41,8 @@ installed on this machine. Show every `DRIFT` line in the report under **Upstrea
|
|
|
41
41
|
line means: review the upstream diff, port what fits, then update `.github/upstream-sources.json`.
|
|
42
42
|
Say nothing for `UP-TO-DATE`, `NOT-INSTALLED` or `NO-SOURCES` (no record: not the caddis source repo).
|
|
43
43
|
The check never fails the review.
|
|
44
|
+
This local check is blind when the upstream plugin is off. `--remote` asks GitHub instead, and the weekly
|
|
45
|
+
`upstream-drift` workflow runs it and keeps one "Upstream drift: obra/superpowers" issue open.
|
|
44
46
|
|
|
45
47
|
## Step 3 — offer to apply
|
|
46
48
|
|
|
@@ -52,6 +52,7 @@
|
|
|
52
52
|
|-------|------|-------------|
|
|
53
53
|
| Changelog Generator | `changelog-generator/` | Create user-facing changelogs and release notes from git commit history, grouping changes and rewriting technical commits in plain language. |
|
|
54
54
|
| Deploy Local | `deploy-local/` | Local deployment loop for Gitea-hosted projects: commit on dev, push, watch the golden CI/build/deploy workflow, check prod, and fix lint/test/pipeline failures until the deploy is healthy. |
|
|
55
|
+
| Graph Email | `graph-email/` | Email a Markdown file via Microsoft Graph or SMTP. Use to email a draft or note. |
|
|
55
56
|
| Monorepo | `monorepo/` | Turborepo and pnpm workspaces: turbo.json tasks, remote caching, shared packages, affected-only CI, apps/ vs packages/ layout, and pitfalls like circular deps, version drift and hoisting. |
|
|
56
57
|
| Runner Move | `runner-move/` | >- |
|
|
57
58
|
| 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. |
|