@caddis/cli 0.4.91 → 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.
Files changed (74) hide show
  1. package/README.md +4 -0
  2. package/bundles/antigravity-plugin/agents/debug.md +2 -0
  3. package/bundles/antigravity-plugin/plugin.json +1 -1
  4. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
  5. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
  6. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
  7. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
  8. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
  9. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
  10. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
  11. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
  12. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
  13. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
  14. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
  15. package/bundles/antigravity-plugin/scripts/caddis_checkout_guard.py +1 -1
  16. package/bundles/antigravity-plugin/scripts/caddis_fleet.py +26 -9
  17. package/bundles/antigravity-plugin/scripts/caddis_gate.py +8 -8
  18. package/bundles/antigravity-plugin/scripts/caddis_guide.json +58 -6
  19. package/bundles/antigravity-plugin/scripts/caddis_lanes.py +17 -17
  20. package/bundles/antigravity-plugin/scripts/caddis_preload_review.py +554 -0
  21. package/bundles/antigravity-plugin/scripts/caddis_review.py +1 -1
  22. package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +25 -39
  23. package/bundles/antigravity-plugin/scripts/caddis_routing.py +1 -1
  24. package/bundles/antigravity-plugin/scripts/caddis_run.py +160 -0
  25. package/bundles/antigravity-plugin/scripts/caddis_spawn.py +17 -1
  26. package/bundles/antigravity-plugin/scripts/caddis_spend.py +121 -138
  27. package/bundles/antigravity-plugin/scripts/caddis_upstream_check.py +108 -10
  28. package/bundles/antigravity-plugin/scripts/oss_review.py +15 -13
  29. package/bundles/antigravity-plugin/scripts/roadmap-recheck.ps1 +4 -2
  30. package/bundles/antigravity-plugin/scripts/schemas/hub-collect.schema.json +6 -0
  31. package/bundles/antigravity-plugin/scripts/schemas/hub-spend.schema.json +6 -0
  32. package/bundles/antigravity-plugin/scripts/setup_project_ai.py +65 -1
  33. package/bundles/antigravity-plugin/skills/_registry.md +3 -1
  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/cross-review/SKILL.md +1 -1
  37. package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +8 -2
  38. package/bundles/antigravity-plugin/skills/fleet-close/SKILL.md +4 -1
  39. package/bundles/antigravity-plugin/skills/graph-email/SKILL.md +15 -0
  40. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +9 -2
  41. package/bundles/antigravity-plugin/skills/implement/SKILL.md +10 -6
  42. package/bundles/antigravity-plugin/skills/particle-art/SKILL.md +1 -3
  43. package/bundles/antigravity-plugin/skills/preload-review/SKILL.md +69 -0
  44. package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +10 -6
  45. package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md +7 -6
  46. package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md +5 -0
  47. package/bundles/antigravity-plugin/skills/tdd/SKILL.md +2 -1
  48. package/bundles/antigravity-plugin/skills/usage-review/SKILL.md +2 -0
  49. package/bundles/antigravity-plugin-extras/plugin.json +1 -1
  50. package/bundles/antigravity-plugin-extras/skills/_registry.md +1 -0
  51. package/bundles/antigravity-plugin-extras/skills/graph-email/SKILL.md +53 -0
  52. package/bundles/antigravity-plugin-extras/skills/graph-email/email.toml.example +44 -0
  53. package/bundles/antigravity-plugin-extras/skills/graph-email/scripts/send_email.py +432 -0
  54. package/bundles/codex/.codex/skills/media/particle-art/SKILL.md +1 -3
  55. package/bundles/codex/.codex/skills/workflow/brainstorming/SKILL.md +232 -40
  56. package/bundles/codex/.codex/skills/workflow/brainstorming/builder-check-prompt.md +25 -0
  57. package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +10 -6
  58. package/bundles/codex/.codex/skills/workflow/roadmap/assets/plan-resume-prompt.md +7 -6
  59. package/bundles/manifest.json +3 -3
  60. package/dist/export/assets/export-CMtV-slT.css +1 -0
  61. package/dist/export/index.html +2 -2
  62. package/dist/ui/assets/{Activity-DZKPMOeV.js → Activity-BDjet2xd.js} +1 -1
  63. package/dist/ui/assets/Guide-Czn5sK0f.js +9 -0
  64. package/dist/ui/assets/Guide-D-Zy4cUT.css +1 -0
  65. package/dist/ui/assets/{RoadmapTab-DPsiSmIF.js → RoadmapTab-Bd8geyQx.js} +1 -1
  66. package/dist/ui/assets/index-Bd0Z4jR8.css +1 -0
  67. package/dist/ui/assets/{index-xl156OCN.js → index-CmngQ8Mk.js} +12 -12
  68. package/dist/ui/index.html +2 -2
  69. package/package.json +1 -1
  70. package/dist/export/assets/export-HxTgj3z2.css +0 -1
  71. package/dist/ui/assets/Guide-5ZFfL6sl.js +0 -9
  72. package/dist/ui/assets/Guide-Dnsb-TRd.css +0 -1
  73. package/dist/ui/assets/index-DGlNAmeA.css +0 -1
  74. /package/dist/export/assets/{export-B7BBDg5I.js → export-DtlDFN4L.js} +0 -0
@@ -34,8 +34,9 @@ Exit codes (fail-closed):
34
34
  denylisted path / possible secret; see secret_filter.py), OR an explicit
35
35
  --range has no changes (a review of nothing is not CLEAN), OR every
36
36
  provider failed with a PROVIDER failure: HTTP 429, any 5xx, a timeout, a
37
- connection error, an empty reply, an agy error status, the agy spend
38
- cap refused, or a one-file prompt too long for agy with no other provider
37
+ connection error, an empty reply, an agy error status, caddis_spend
38
+ refused agy (headless depth or log lock), or a one-file prompt too
39
+ long for agy with no other provider
39
40
  — actionable message on stderr/stdout either way
40
41
  4 error — no diff verdict parsed, git failure, other endpoint/parse failure, or the diff
41
42
  exceeds REVIEW_MAX_DIFF_CHARS (see below — never silently downgraded to CLEAN)
@@ -52,7 +53,7 @@ A named --provider goes first, then the rest in policy order; a provider with no
52
53
  is skipped. With no provider named, the chain starts at the first provider that is available. A provider failure
53
54
  moves to the next provider and never splits the diff. On HTTP 429 a `Retry-After` is honoured ONCE per
54
55
  provider (capped at 60 s), then the next provider is tried. A provider that failed gets no more calls in
55
- the same run. agy runs through `caddis_spend.py run` (the EUR spend cap), in plan mode, with the diff in
56
+ the same run. agy runs through `caddis_spend.py run` (usage log, timeout, depth guard; no EUR cap), in plan mode, with the diff in
56
57
  the prompt (no tools needed). The secret filter runs once, before any provider, agy included. The
57
58
  provider that gave each verdict is printed.
58
59
 
@@ -141,7 +142,7 @@ AGY_PROVIDER = "agy-argon"
141
142
  DEFAULT_PROVIDER = AGY_PROVIDER
142
143
  REVIEW_ORDER: tuple[str, ...] = (AGY_PROVIDER, "deepseek", "glm")
143
144
 
144
- # agy runs headless through the spend cap: plan mode (it needs no tools, the diff is in the prompt).
145
+ # agy runs headless through caddis_spend.py run: plan mode (it needs no tools, the diff is in the prompt).
145
146
  AGY_MODEL = "gemini-4-argon-high"
146
147
  AGY_TIMEOUT_S = 15 * 60
147
148
  # The prompt is one command-line argument (`--print=<prompt>`). A Windows command line holds at most
@@ -152,8 +153,9 @@ AGY_TIMEOUT_S = 15 * 60
152
153
  # the longest command line: python, two script paths, the agy path and the fixed flags.
153
154
  WINDOWS_CMDLINE_MAX = 32_767
154
155
  AGY_MAX_PROMPT_CHARS = 28_000
155
- # `caddis_spend.py run` refusal codes: 75 over the cap or no lock, 78 cap not configured. Never agy's own.
156
- SPEND_REFUSED = (75, 78)
156
+ # `caddis_spend.py run` refusal code: 75 = headless depth at its limit, or the usage log could not be locked or
157
+ # written. Never agy's own. (78 "cap not configured" is gone with the cap, 1 Nov 2026.)
158
+ SPEND_REFUSED = (75,)
157
159
 
158
160
  # On HTTP 429, wait for `Retry-After` once per provider per run, at most this long.
159
161
  RETRY_AFTER_CAP_S = 60.0
@@ -213,7 +215,7 @@ class ProviderFailure(RuntimeError):
213
215
 
214
216
 
215
217
  class ProviderSkipped(Exception):
216
- """The provider is not available for this run (the spend cap refused agy, agy is missing, the prompt
218
+ """The provider is not available for this run (caddis_spend refused agy, agy is missing, the prompt
217
219
  is too long for the agy command line). The chain moves on; nothing was reviewed. `for_run=False`: skip only
218
220
  this prompt (it was too long), so a smaller batch may still use the provider."""
219
221
 
@@ -635,8 +637,8 @@ def _spend_script() -> Path | None:
635
637
 
636
638
 
637
639
  def agy_launcher() -> list[str] | None:
638
- """The command prefix that runs agy under the spend cap, or None when agy or caddis_spend is missing.
639
- Every agy call goes through `caddis_spend.py run` (owner policy: agy only through the spend cap)."""
640
+ """The command prefix that runs agy through `caddis_spend.py run`, or None when agy or caddis_spend is missing.
641
+ Every agy call goes through `caddis_spend.py run` (usage log, timeout and depth guard; there is no EUR cap)."""
640
642
  agy = shutil.which("agy")
641
643
  spend = _spend_script()
642
644
  if not agy or spend is None:
@@ -704,9 +706,9 @@ def agy_prompt_chars(prompt: str) -> int:
704
706
 
705
707
 
706
708
  def call_agy(launcher: list[str], prompt: str, timeout: float = AGY_TIMEOUT_S) -> str:
707
- """One review by agy Argon through the spend cap -> the reply text.
709
+ """One review by agy Argon through `caddis_spend.py run` -> the reply text.
708
710
 
709
- ProviderSkipped: the cap refused, agy is missing, or the prompt is too long for one argument.
711
+ ProviderSkipped: caddis_spend refused (exit 75), agy is missing, or the prompt is too long for one argument.
710
712
  ProviderFailure: a non-zero exit, a status other than SUCCESS (ERROR, RESOURCE_EXHAUSTED), no JSON
711
713
  document, or an empty reply."""
712
714
  cost = agy_prompt_chars(prompt)
@@ -717,7 +719,7 @@ def call_agy(launcher: list[str], prompt: str, timeout: float = AGY_TIMEOUT_S) -
717
719
  f"--print={prompt}"]
718
720
  code, stdout, stderr = _run_capped(argv, timeout)
719
721
  if code in SPEND_REFUSED:
720
- raise ProviderSkipped(f"the agy spend cap refused the call (caddis_spend exit {code}): "
722
+ raise ProviderSkipped(f"caddis_spend refused the agy call (exit {code}): "
721
723
  f"{stderr.strip()[-300:]}")
722
724
  if code == 127:
723
725
  raise ProviderSkipped(f"agy could not start: {stderr.strip()[-300:]}")
@@ -1003,7 +1005,7 @@ def main(argv: list[str] | None = None, env: dict[str, str] | None = None) -> in
1003
1005
  + "). Verdict is CLEAN only if every batch is clean."
1004
1006
  )
1005
1007
 
1006
- # Per run: a provider that failed (429, 5xx, timeout, empty reply, cap refusal) gets no more calls,
1008
+ # Per run: a provider that failed (429, 5xx, timeout, empty reply, caddis_spend refusal) gets no more calls,
1007
1009
  # and each provider waits for a 429 Retry-After at most once. Hammering a throttled provider with
1008
1010
  # more, smaller calls is the 18-19 Oct 2026 failure.
1009
1011
  down: set[str] = set()
@@ -9,7 +9,9 @@
9
9
  # 3. `caddis_roadmap.py recheck` cleared a blocker (exit 0); in a `merged:`, `freed:` or `rollup-ready:` tick
10
10
  # recheck is NOT run (the
11
11
  # merge is the change, and a cleared blocker would change the roadmap the restart checks against its hash);
12
- # 4. agy engine only (the recorded launch options): `caddis_spend.py check` exits 0.
12
+ # 4. agy engine only (the recorded launch options): `caddis_spend.py check` exits 0. There is no spend cap (1 Nov
13
+ # 2026), so check always exits 0 and prints the usage line (with ADVISORY at the advise level); a non-zero
14
+ # exit now means the script itself failed.
13
15
  # It restarts with the launch options the last run recorded (`--restart-args`: engine, model, caps), never the
14
16
  # defaults. A run that holds the lock records the last stop `running`, so a run killed without a stop (a crash, a
15
17
  # reboot) is never restarted here: it needs the owner.
@@ -72,7 +74,7 @@ $options = @(& $py $runnerPy --roadmap $Roadmap --repo $Repo --restart-args | Wh
72
74
  if ($LASTEXITCODE -ne 0) { Write-Output "roadmap-recheck: launch options not readable; runner not started"; exit 1 }
73
75
  if ($GhAccount -and $options -notcontains '-GhAccount') { $options += @('-GhAccount', $GhAccount) }
74
76
 
75
- # The global agy spend cap applies to the agy engine only (a claude run needs no spend-cap file).
77
+ # agy engine only: print the agy usage line (no cap; check exits 0 unless the script itself fails).
76
78
  $engineAt = [array]::IndexOf($options, '-Engine')
77
79
  $engine = if ($engineAt -ge 0 -and $engineAt + 1 -lt $options.Count) { $options[$engineAt + 1] } else { 'claude' }
78
80
  if ($engine -eq 'agy') {
@@ -674,6 +674,12 @@
674
674
  },
675
675
  "window_h": {
676
676
  "type": "integer"
677
+ },
678
+ "advise_eur": {
679
+ "type": "number"
680
+ },
681
+ "advisory": {
682
+ "type": "boolean"
677
683
  }
678
684
  }
679
685
  },
@@ -34,6 +34,12 @@
34
34
  },
35
35
  "window_h": {
36
36
  "type": "integer"
37
+ },
38
+ "advise_eur": {
39
+ "type": "number"
40
+ },
41
+ "advisory": {
42
+ "type": "boolean"
37
43
  }
38
44
  }
39
45
  }
@@ -1201,6 +1201,7 @@ agent-log.jsonl
1201
1201
  usage-log.jsonl.1
1202
1202
  agent-log.jsonl.1
1203
1203
  .last-usage-review
1204
+ .last-preload-review
1204
1205
  relay.md
1205
1206
  relay/
1206
1207
  session-state.md
@@ -1490,6 +1491,68 @@ def ensure_user_env(dry: bool, home: Path | None = None) -> list[str]:
1490
1491
  + ("" if not raw else " (previous version saved as settings.json.caddis-bak)")]
1491
1492
 
1492
1493
 
1494
+ # ── superpowers twins that caddis replaces ──────────────────────────────────────────────────
1495
+ # caddis owns the routing-critical skills: brainstorming, plans (/caddis:feature-plan), running plans
1496
+ # (/caddis:implement) and worktrees. The superpowers plugin ships skills with the same names; its
1497
+ # writing-plans and executing-plans skip the caddis model routing. A deny rule blocks such a skill
1498
+ # ("Skill execution blocked by permission rules") WITHOUT a prompt, so it keeps the zero-prompt setup
1499
+ # (an `ask` rule would prompt every time). Every other superpowers skill is used straight from the plugin.
1500
+ # inject_relay.py re-states this list to warn when a rule is missing; a test keeps the two equal.
1501
+ SUPERPOWERS_DENY = (
1502
+ "Skill(superpowers:brainstorming)",
1503
+ "Skill(superpowers:writing-plans)",
1504
+ "Skill(superpowers:executing-plans)",
1505
+ "Skill(superpowers:subagent-driven-development)",
1506
+ "Skill(superpowers:using-git-worktrees)",
1507
+ )
1508
+
1509
+
1510
+ def ensure_superpowers_deny(dry: bool, home: Path | None = None) -> str:
1511
+ """Add the SUPERPOWERS_DENY rules to the user's `permissions.deny`, additively and idempotently.
1512
+
1513
+ Other deny entries (and every other setting) are never removed or reordered. Same safety rules as
1514
+ ensure_user_env: a file that does not parse is never rewritten, a backup is kept
1515
+ (`settings.json.caddis-deny-bak`, its own name so it cannot overwrite another function's backup), the
1516
+ write is atomic, and `CADDIS_NO_SETTINGS_ENV` skips it. Known limit, as for ensure_user_env: a write by
1517
+ Claude Code between this read and the replace is lost."""
1518
+ if os.environ.get("CADDIS_NO_SETTINGS_ENV"):
1519
+ return "superpowers deny rules: skipped (CADDIS_NO_SETTINGS_ENV set)"
1520
+ path = _user_settings_path(home)
1521
+ if path.is_file():
1522
+ raw = path.read_text(encoding="utf-8", errors="ignore")
1523
+ try:
1524
+ data = json.loads(raw)
1525
+ except json.JSONDecodeError as exc:
1526
+ return (f"superpowers deny rules: {path} is NOT VALID JSON ({exc.msg}, line {exc.lineno}) — "
1527
+ "left untouched; fix it by hand.")
1528
+ if not isinstance(data, dict):
1529
+ return f"superpowers deny rules: {path} is not a JSON object — left untouched"
1530
+ else:
1531
+ raw, data = "", {}
1532
+ perms = data.get("permissions")
1533
+ if perms is None:
1534
+ perms = {}
1535
+ elif not isinstance(perms, dict):
1536
+ return f"superpowers deny rules: {path} has a non-object `permissions` — left untouched"
1537
+ deny = perms.get("deny")
1538
+ if deny is None:
1539
+ deny = []
1540
+ elif not isinstance(deny, list):
1541
+ return f"superpowers deny rules: {path} has a non-list `permissions.deny` — left untouched"
1542
+ missing = [rule for rule in SUPERPOWERS_DENY if rule not in deny]
1543
+ if not missing:
1544
+ return f"superpowers deny rules: all {len(SUPERPOWERS_DENY)} already in {path}"
1545
+ perms["deny"] = deny + missing
1546
+ data["permissions"] = perms
1547
+ if not dry:
1548
+ path.parent.mkdir(parents=True, exist_ok=True)
1549
+ if raw:
1550
+ path.with_suffix(".json.caddis-deny-bak").write_text(raw, encoding="utf-8")
1551
+ _atomic_write_json(path, data)
1552
+ verb = "would add" if dry else "added"
1553
+ return f"superpowers deny rules: {verb} {len(missing)} to permissions.deny in {path}"
1554
+
1555
+
1493
1556
  CLEANUP_PERIOD_KEY = "cleanupPeriodDays"
1494
1557
  CLEANUP_PERIOD_DAYS = 120
1495
1558
 
@@ -1534,7 +1597,7 @@ def scaffold_artifact_dir(target: Path, dry: bool) -> list[str]:
1534
1597
  """Create the harness-owned .caddis/ artifact tree + a default .gitignore + a config example.
1535
1598
 
1536
1599
  Committed subdirs: plans, handoffs, agent-docs, prd, kb, prompts, comms. Transient state
1537
- (reviews/*.html, usage-log.jsonl, .last-usage-review, relay*, session-state.md,
1600
+ (reviews/*.html, usage-log.jsonl, .last-usage-review, .last-preload-review, relay*, session-state.md,
1538
1601
  PROJECT-FACTS.md) is gitignored. .caddis/ is the default home for every working-artifact kind (Track A
1539
1602
  Phase A3) — kb/ and prompts/ round out plans/prd/agent-docs/reviews so nothing has to
1540
1603
  scatter to the repo root or .github/. Also drops a documented `config.toml.example`
@@ -1832,6 +1895,7 @@ def main() -> int:
1832
1895
  for line in ensure_user_env(args.dry_run):
1833
1896
  print(f" {line}")
1834
1897
  print(f" {ensure_cleanup_period(args.dry_run)}")
1898
+ print(f" {ensure_superpowers_deny(args.dry_run)}")
1835
1899
 
1836
1900
  print("-- doc-coverage discipline (DOC-MAP + page guide + checker)")
1837
1901
  for line in emit_doc_discipline(target, ident, args.force, args.dry_run):
@@ -40,6 +40,7 @@
40
40
  | Ci Cd Pipeline | `ci-cd-pipeline/` | CI/CD pipelines for GitHub Actions and Azure DevOps: build and deploy workflows, quality gates, environment promotion and release automation. |
41
41
  | Gh Cli | `gh-cli/` | GitHub CLI operations — issues, PRs, releases, and repo management |
42
42
  | Git Commit | `git-commit/` | Create well-structured conventional commit messages following Conventional Commits standard. Use when committing changes, preparing PRs, or generating changelogs. |
43
+ | Graph Email | `graph-email/` | Send a Markdown file as an email through Microsoft Graph or SMTP, as set in ~/.caddis/email.toml. Default recipient is the owner. |
43
44
  | Port To Github | `port-to-github/` | >- |
44
45
  | 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. |
45
46
  | Using Git Worktrees | `using-git-worktrees/` | Use when starting feature work that needs isolation from the current workspace, or before executing an implementation plan: creates an isolated git worktree safely. |
@@ -100,6 +101,7 @@
100
101
  | Park | `park/` | File a future-work item in the one backlog — .caddis/parking-lot/ — or list what is open |
101
102
  | Pr Merge | `pr-merge/` | End-to-end pull request and merge lane — push feature branch, open or update PR, monitor CI to green, merge to default branch, and clean up the feature branch. |
102
103
  | Prd | `prd/` | Capture requirements through structured discovery and write a PRD |
104
+ | Preload Review | `preload-review/` | Show what loads before the first prompt in every repo (rules, memory index, skills, MCP names) and list what to shorten |
103
105
  | Rca | `rca/` | Record a root cause in one step — .caddis/rca/<date>-<slug>.md — or close one with the fixing commit |
104
106
  | Review Pr | `review-pr/` | Review someone else's OPEN pull request end to end — what changed, what CI says, what is risky — then approve or request changes. Never approves on its own. |
105
107
  | Ship | `ship/` | Commit, push, and monitor the deploy pipeline (auto-detects Gitea, GitHub Actions, or local-only) |
@@ -135,7 +137,7 @@
135
137
  | Skill | Path | When to Use |
136
138
  |-------|------|-------------|
137
139
  | Best Practices | `best-practices/` | >- |
138
- | Brainstorming | `brainstorming/` | You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. |
140
+ | Brainstorming | `brainstorming/` | Use before any creative work: new features, components or behavior changes, or planning anything new. Finds what the user wants first. |
139
141
  | Context Curator | `context-curator/` | Compress and prioritize codebase context before handing work to reasoning agents, minimizing token waste while preserving the required decision inputs. |
140
142
  | Preflight | `preflight/` | Plan-vs-codebase validation — verifies API contracts, type names, field accuracy, dependencies, and paths before implementation begins |
141
143
  | Roadmap | `roadmap/` | Track milestones across plans in .caddis/roadmaps/<slug>/: next batch, typed blockers, rollup. Every change is a docs PR via caddis_roadmap.py. |
@@ -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
+ ```
@@ -101,7 +101,7 @@ and never report the result as a full CLEAN.
101
101
  then DeepSeek, then GLM** (`REVIEW_ORDER` in `oss_review.py`). A named `--provider` goes first; on a provider failure
102
102
  (HTTP 429, any 5xx, a timeout, a connection error, an empty reply) the tool moves to the next one in
103
103
  that order and prints which provider gave the verdict. A provider with no key is skipped. agy runs
104
- through `caddis_spend.py run` (the spend cap); if the cap refuses, agy is skipped. On a 429 the tool
104
+ through `caddis_spend.py run` (usage log, time limit, depth guard; no spend cap); if it refuses (exit 75), agy is skipped. On a 429 the tool
105
105
  waits for `Retry-After` once (at most 60 s); it never splits the diff because of a 429 or an empty
106
106
  reply. A custom endpoint (`--base-url`/`--model`) never falls back. Name a provider only when you have
107
107
  a reason.
@@ -182,7 +182,7 @@ of that role and write its Lane line as follows:
182
182
  - `agy`: agy — `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spend.py" run --caller lane-pN -- agy --mode accept-edits --dangerously-skip-permissions --add-dir . --print-timeout 20m --output-format json -p "HEADLESS RUN RULES. Read <plan path> and its Constraints. Implement Phase N only in the current checkout. Do not switch or create branches, commit, push, or edit files outside this phase. Run its exit gate and report the literal result."`
183
183
 
184
184
  Replace `<plan path>` and `N` (also in `lane-pN`) with this plan's path and phase number. The agy line
185
- always starts with `caddis_spend.py run`: it books the call against the global EUR spend cap, and
185
+ always starts with `caddis_spend.py run`: it logs the call's usage and sets its time limit (there is no spend cap), and
186
186
  `caddis_gate.py lane-check` refuses a bare `agy` Lane line. If the routing command fails
187
187
  or exits 3, use `claude — this session` and state the reason in that phase. When a phase has cards, a
188
188
  prompt for one card names it by reference ("then Phase N card B"). Never paste card text into a prompt.
@@ -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>