@caddis/cli 0.4.88 → 0.4.90
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 +46 -0
- package/bundles/antigravity-plugin/agents/preflight.md +4 -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_fleet.py +37 -10
- package/bundles/antigravity-plugin/scripts/caddis_guide.json +16 -11
- package/bundles/antigravity-plugin/scripts/caddis_handoff.py +370 -0
- package/bundles/antigravity-plugin/scripts/caddis_heartbeat.py +339 -0
- package/bundles/antigravity-plugin/scripts/caddis_hub_collect.py +37 -8
- package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +130 -63
- package/bundles/antigravity-plugin/scripts/caddis_routing.py +36 -0
- package/bundles/antigravity-plugin/scripts/caddis_todo.py +55 -10
- package/bundles/antigravity-plugin/scripts/caddis_workstreams.py +35 -12
- package/bundles/antigravity-plugin/scripts/schemas/hub-collect.schema.json +42 -0
- package/bundles/antigravity-plugin/scripts/schemas/hub-plans.schema.json +23 -0
- package/bundles/antigravity-plugin/session_end_agy.py +26 -1
- package/bundles/antigravity-plugin/skills/code-review/SKILL.md +2 -0
- package/bundles/antigravity-plugin/skills/coordinate/SKILL.md +5 -3
- package/bundles/antigravity-plugin/skills/cross-review/SKILL.md +1 -0
- package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +47 -19
- package/bundles/antigravity-plugin/skills/fleet-open/SKILL.md +1 -1
- package/bundles/antigravity-plugin/skills/handoff/SKILL.md +82 -7
- package/bundles/antigravity-plugin/skills/implement/SKILL.md +86 -6
- package/bundles/antigravity-plugin/skills/park/SKILL.md +1 -0
- package/bundles/antigravity-plugin/skills/preflight/SKILL.md +1 -0
- package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md +8 -1
- package/bundles/antigravity-plugin/warm_start_agy.py +29 -1
- package/bundles/antigravity-plugin-extras/plugin.json +1 -1
- package/bundles/antigravity-plugin-extras/skills/cross-review/SKILL.md +1 -0
- package/bundles/codex/.codex/skills/coding/code-review/SKILL.md +2 -0
- package/bundles/codex/.codex/skills/workflow/preflight/SKILL.md +1 -0
- package/bundles/codex/.codex/skills/workflow/roadmap/assets/plan-resume-prompt.md +8 -1
- package/bundles/manifest.json +3 -3
- package/dist/allowed-urls.txt +3 -2
- package/dist/cli.js +554 -275
- package/dist/export/assets/export-B7BBDg5I.js +150 -0
- package/dist/export/assets/export-HxTgj3z2.css +1 -0
- package/dist/export/assets/mark-anim-DZa95SHo.webp +0 -0
- package/dist/export/assets/mark-still-CcPgBc_-.png +0 -0
- package/dist/export/fonts/ibm-plex-mono-400.6d569bb7.woff2 +0 -0
- package/dist/export/fonts/ibm-plex-mono-700.9f478677.woff2 +0 -0
- package/dist/export/fonts/ibm-plex-sans-400.17fc1ce7.woff2 +0 -0
- package/dist/export/fonts/ibm-plex-sans-500.dcc69acf.woff2 +0 -0
- package/dist/export/fonts/ibm-plex-sans-600.d4dad061.woff2 +0 -0
- package/dist/export/fonts/ibm-plex-sans-700.40d9a530.woff2 +0 -0
- package/dist/export/index.html +2 -2
- package/dist/export/licenses/{OFL-MapleMono.txt → OFL-IBMPlexMono.txt} +4 -4
- package/dist/{ui/licenses/OFL-MapleMono.txt → export/licenses/OFL-IBMPlexSans.txt} +4 -4
- package/dist/ui/assets/{Activity-C9TCizJV.js → Activity-DZKPMOeV.js} +1 -1
- package/dist/ui/assets/Guide-5ZFfL6sl.js +9 -0
- package/dist/ui/assets/Guide-Dnsb-TRd.css +1 -0
- package/dist/ui/assets/RoadmapTab-DPsiSmIF.js +31 -0
- package/dist/ui/assets/index-DGlNAmeA.css +1 -0
- package/dist/ui/assets/index-xl156OCN.js +231 -0
- package/dist/ui/assets/mark-anim-DZa95SHo.webp +0 -0
- package/dist/ui/assets/mark-still-CcPgBc_-.png +0 -0
- package/dist/ui/fonts/ibm-plex-mono-400.6d569bb7.woff2 +0 -0
- package/dist/ui/fonts/ibm-plex-mono-700.9f478677.woff2 +0 -0
- package/dist/ui/fonts/ibm-plex-sans-400.17fc1ce7.woff2 +0 -0
- package/dist/ui/fonts/ibm-plex-sans-500.dcc69acf.woff2 +0 -0
- package/dist/ui/fonts/ibm-plex-sans-600.d4dad061.woff2 +0 -0
- package/dist/ui/fonts/ibm-plex-sans-700.40d9a530.woff2 +0 -0
- package/dist/ui/index.html +2 -2
- package/dist/{export/licenses/OFL-Atkinson.txt → ui/licenses/OFL-IBMPlexMono.txt} +3 -3
- package/dist/ui/licenses/{OFL-Atkinson.txt → OFL-IBMPlexSans.txt} +3 -3
- package/package.json +4 -1
- package/dist/export/assets/export-CEtCs5rg.css +0 -1
- package/dist/export/assets/export-v-kcNvPW.js +0 -150
- package/dist/export/assets/mark-small-B1q4Vk3J.svg +0 -8
- package/dist/export/fonts/atkinson-400.849ae6f0.woff2 +0 -0
- package/dist/export/fonts/atkinson-500.21d6ef26.woff2 +0 -0
- package/dist/export/fonts/atkinson-600.ce9f3210.woff2 +0 -0
- package/dist/export/fonts/atkinson-700.3a9cc18a.woff2 +0 -0
- package/dist/export/fonts/maple-mono-400.071799fd.woff2 +0 -0
- package/dist/export/fonts/maple-mono-700.1e17b237.woff2 +0 -0
- package/dist/ui/assets/Guide-6aEYW9oW.js +0 -9
- package/dist/ui/assets/Guide-zcVFGUxR.css +0 -1
- package/dist/ui/assets/RoadmapTab-hUK2kzCW.js +0 -31
- package/dist/ui/assets/index-DE7v-v_o.css +0 -1
- package/dist/ui/assets/index-d44hkSAE.js +0 -221
- package/dist/ui/assets/mark-small-B1q4Vk3J.svg +0 -8
- package/dist/ui/fonts/atkinson-400.849ae6f0.woff2 +0 -0
- package/dist/ui/fonts/atkinson-500.21d6ef26.woff2 +0 -0
- package/dist/ui/fonts/atkinson-600.ce9f3210.woff2 +0 -0
- package/dist/ui/fonts/atkinson-700.3a9cc18a.woff2 +0 -0
- package/dist/ui/fonts/maple-mono-400.071799fd.woff2 +0 -0
- package/dist/ui/fonts/maple-mono-700.1e17b237.woff2 +0 -0
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
"""caddis `session_end` hook for agy (Antigravity) — Stop event.
|
|
3
3
|
|
|
4
4
|
Ports claude-harness/hooks/session_end.py to agy's contract. On Stop, appends ONE session-end record to
|
|
5
|
-
the workspace's usage log (`<workspace>/.caddis/usage-log.jsonl`)
|
|
5
|
+
the workspace's usage log (`<workspace>/.caddis/usage-log.jsonl`), and marks the session `waiting` in
|
|
6
|
+
its status file `~/.caddis/sessions/<conversationId>.json` (the caddis hub's session list). Self-contained (the agy bundle does not
|
|
6
7
|
ship claudster_config.py), stdlib-only, and fully defensive:
|
|
7
8
|
a Stop hook must never fail the turn, and must not print a non-JSON line to stdout (agy parses Stop-hook
|
|
8
9
|
stdout as a `{"decision":…}` object — a stray string trips its "unsupported hook decision" path). So this
|
|
@@ -86,6 +87,28 @@ def _hook_note(feature, exc, root=None):
|
|
|
86
87
|
pass
|
|
87
88
|
|
|
88
89
|
|
|
90
|
+
|
|
91
|
+
def _status_beat(data, status):
|
|
92
|
+
"""Write this agy session's status for the caddis hub (~/.caddis/sessions/). Never raises, never prints.
|
|
93
|
+
|
|
94
|
+
caddis_heartbeat.py ships under scripts/ in the agy bundle; in the source repo it is in
|
|
95
|
+
claude-harness/scripts/. Headless runs (review and lane runs) write nothing.
|
|
96
|
+
"""
|
|
97
|
+
try:
|
|
98
|
+
if str(os.environ.get("CADDIS_HEADLESS", "")).strip():
|
|
99
|
+
return
|
|
100
|
+
_here = os.path.dirname(os.path.abspath(__file__))
|
|
101
|
+
for _cand in (os.path.join(_here, "scripts"),
|
|
102
|
+
os.path.join(os.path.dirname(_here), "scripts")):
|
|
103
|
+
if os.path.isfile(os.path.join(_cand, "caddis_heartbeat.py")):
|
|
104
|
+
if _cand not in sys.path:
|
|
105
|
+
sys.path.insert(0, _cand)
|
|
106
|
+
break
|
|
107
|
+
import caddis_heartbeat as _hb # noqa: E402
|
|
108
|
+
_hb.agy_beat(data, status, plugin_root=_here) # the bundle's plugin.json sits beside the hook
|
|
109
|
+
except Exception as _exc:
|
|
110
|
+
_hook_note("agy session status", _exc)
|
|
111
|
+
|
|
89
112
|
def _workspace_roots(data):
|
|
90
113
|
"""Every workspace root in the payload, as a list. Empty when the payload has none.
|
|
91
114
|
|
|
@@ -119,6 +142,8 @@ def main() -> None:
|
|
|
119
142
|
data = {}
|
|
120
143
|
if _headless():
|
|
121
144
|
return
|
|
145
|
+
# The turn ended: the session waits for the user. `fullyIdle: false` means agy is not idle yet: it stays working.
|
|
146
|
+
_status_beat(data, "working" if isinstance(data, dict) and data.get("fullyIdle") is False else "waiting")
|
|
122
147
|
try:
|
|
123
148
|
roots = _workspace_roots(data) or [os.getcwd()]
|
|
124
149
|
# A workspace folder may sit inside a repo: the artifact dir is the REPO ROOT's, not the sub-folder's.
|
|
@@ -61,6 +61,8 @@ Check for:
|
|
|
61
61
|
|
|
62
62
|
## Review Output Format
|
|
63
63
|
|
|
64
|
+
In a caddis repo, save a review note in `.caddis/reviews/`, never in `.caddis/parking-lot/`: that folder holds only items to do later, one item per file, `type: parking-lot`.
|
|
65
|
+
|
|
64
66
|
```markdown
|
|
65
67
|
## Code Review Summary
|
|
66
68
|
|
|
@@ -29,11 +29,13 @@ Argument: **$ARGUMENTS**
|
|
|
29
29
|
## Keep this session cheap
|
|
30
30
|
|
|
31
31
|
Measured 24-25 Oct 2026: each background wake-up re-reads the whole conversation.
|
|
32
|
-
- Start the coordinator on
|
|
33
|
-
|
|
32
|
+
- Start the coordinator on the model and effort of the session table:
|
|
33
|
+
`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_routing.py" session --role coordinator` prints `<model> <effort>`
|
|
34
|
+
(today `sonnet low`). Then run `claude --model <model> --effort <effort> --name coordinator`, then
|
|
35
|
+
`/caddis:coordinate start`.
|
|
34
36
|
- Post a peer message only when the queue or a PR state changes. Send no acknowledgement of an
|
|
35
37
|
acknowledgement. The watcher already prints a line only on a change, so a quiet cycle wakes nobody.
|
|
36
|
-
- Restart (handoff
|
|
38
|
+
- Restart with the full handoff (`/caddis:handoff`, `/clear`, `/caddis:coordinate`) when this conversation passes about 200k tokens, or once a day. The coordinator never runs the checkpoint: `caddis_handoff.py checkpoint` refuses the coordinator's relay. The context_size hook prints a [caddis] warning at 200k and a stop line at 280k.
|
|
37
39
|
|
|
38
40
|
## How to call the script
|
|
39
41
|
|
|
@@ -124,6 +124,7 @@ change, so a batch does not report the others as missing.
|
|
|
124
124
|
emitted by this tool** — across caddis 2 always means an advisory note, and a review
|
|
125
125
|
has no advisory verdict.
|
|
126
126
|
- A different vendor means a different style; weigh its findings on merit, don't cargo-cult them.
|
|
127
|
+
- Save review notes in `.caddis/reviews/`, never in `.caddis/parking-lot/`: that folder holds only items to do later, one item per file, `type: parking-lot` (`/caddis:park`).
|
|
127
128
|
- **Never use `find`, `Get-ChildItem -Recurse`, or any other filesystem-wide search to locate
|
|
128
129
|
`oss_review.py`.** Check only the two paths above. On Git Bash under Windows, `find /` (or any
|
|
129
130
|
search rooted at `/`) walks every mounted drive, not just the repo — it can hang or take minutes.
|
|
@@ -105,18 +105,32 @@ those phases. Put what the scan actually shows into the plan's `## Risks` table.
|
|
|
105
105
|
Before writing the plan, consider dispatching the **preflight** subagent to validate your assumptions
|
|
106
106
|
(paths, symbols, APIs, primitives) against the codebase — it routinely catches wrong assumptions early.
|
|
107
107
|
|
|
108
|
-
### Assign a model
|
|
109
|
-
Match capability to each phase's difficulty — not one model for the whole plan.
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
108
|
+
### Assign a model and an effort per phase (don't default everything to the priciest)
|
|
109
|
+
Match capability to each phase's difficulty — not one model for the whole plan. Every `**Model:**` line
|
|
110
|
+
names the model AND the effort, in this form:
|
|
111
|
+
`**Model:** <model>, effort <low|medium|high> — <one-line reason tied to this phase's difficulty>`.
|
|
112
|
+
Take the default from the session table. It prints `<model> <effort>`:
|
|
113
|
+
```
|
|
114
|
+
python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_routing.py" session --role <role>
|
|
115
|
+
```
|
|
116
|
+
(Source checkout: `claude-harness/scripts/caddis_routing.py`.) Pick the role by the phase:
|
|
117
|
+
- `mechanical-phase` — mechanical, fully specified phases that repeat an existing pattern.
|
|
118
|
+
- `coding-phase` — standard code with a clear spec and literal tests.
|
|
119
|
+
- `critical-phase` — novel architecture, tricky algorithms, security-sensitive or judgment-heavy seams;
|
|
120
|
+
also recommend a `code-reviewer` pass.
|
|
121
|
+
- `measure` — measurement and screenshot work.
|
|
122
|
+
The table also holds the session roles `orchestrator`, `plan-writer` and `coordinator`. Use Claude Code's
|
|
123
|
+
evergreen `/model` aliases (`haiku`, `sonnet`, `opus`) so a line never rots as model names change.
|
|
124
|
+
`/model fable` is RARE: long-horizon work that cannot verify itself, at about 2× opus's rate-limit burn.
|
|
125
|
+
Change the default only with a reason on the line. `max` effort is manual escalation, never a planned
|
|
126
|
+
default. If the command fails, write the model and the effort by hand and say why.
|
|
127
|
+
|
|
128
|
+
**Escalation.** Escalate to Opus through a SMALL subagent (by-reference brief, reply ≤ 10 lines), never `/model opus` mid-session (the prompt cache is per model, so a switch at 200k re-writes the whole cache), when: a card fails again after its one fix card; a measurement fails a rule (isolate the cause first, then give the owner options); a plan amendment changes the design, not only facts; a risk-high phase reaches review. A fresh Opus session only to write a new plan or a redesign.
|
|
129
|
+
|
|
130
|
+
### Size rule: a phase fits one sitting
|
|
131
|
+
One agy card ≤ 6 files; one phase ≤ 12 files and ≤ 6 cards or tasks. Bigger: split (7a, 7b, each with a
|
|
132
|
+
Tracker row) or mark `**Programme phase:** yes — <why>`. A phase that grows past 6 cards during work is
|
|
133
|
+
split in the Tracker first.
|
|
120
134
|
|
|
121
135
|
### Assign an execution LANE per phase (which harness runs it — not just which model)
|
|
122
136
|
A tier can be served by an OSS provider instead of Anthropic (cheat sheet:
|
|
@@ -170,7 +184,8 @@ of that role and write its Lane line as follows:
|
|
|
170
184
|
Replace `<plan path>` and `N` (also in `lane-pN`) with this plan's path and phase number. The agy line
|
|
171
185
|
always starts with `caddis_spend.py run`: it books the call against the global EUR spend cap, and
|
|
172
186
|
`caddis_gate.py lane-check` refuses a bare `agy` Lane line. If the routing command fails
|
|
173
|
-
or exits 3, use `claude — this session` and state the reason in that phase.
|
|
187
|
+
or exits 3, use `claude — this session` and state the reason in that phase. When a phase has cards, a
|
|
188
|
+
prompt for one card names it by reference ("then Phase N card B"). Never paste card text into a prompt.
|
|
174
189
|
|
|
175
190
|
#### A phase may take a no-escalation lane only if its exit gate would fail on a spec error
|
|
176
191
|
`glm-headless` cannot escalate: it does what the phase says. So completeness is only half the test —
|
|
@@ -281,8 +296,10 @@ to the phase or task that owns the code. Write "none found" only after you check
|
|
|
281
296
|
|
|
282
297
|
**Session rules for the orchestrator** (measured 24-25 Oct 2026: long Opus sessions re-read 400-600k tokens
|
|
283
298
|
on every turn). Keep the context small: subagent replies under about 200 words, full reports in files,
|
|
284
|
-
never paste or tail large outputs.
|
|
285
|
-
|
|
299
|
+
never paste or tail large outputs. Context rule: Above 200k: checkpoint at the next card end when 2 or more
|
|
300
|
+
cards are left; else finish the phase and run the full handoff. At 280k: checkpoint at the first moment no
|
|
301
|
+
agent or background command runs. (The checkpoint is the "Checkpoint" section of `/caddis:handoff`; the
|
|
302
|
+
context_size hook prints its exact command.) At each phase end that ends a sitting, write the full handoff. Run the phase review as
|
|
286
303
|
`/caddis:cross-review --range <base>..HEAD`. Send a task marked mechanical (literal tests, moves, deletes,
|
|
287
304
|
renames) to agy through `caddis_spend.py run`. Run one `ci-watch` per PR head; on a queued-run timeout watch
|
|
288
305
|
that run once with `--run <id>`; write no "still waiting" turns.
|
|
@@ -291,11 +308,13 @@ that run once with `--run <id>`; write no "still waiting" turns.
|
|
|
291
308
|
> ⚠️ **Switch model/lane BEFORE starting this phase** — the *active* model does the work, not the
|
|
292
309
|
> one named here. Lane `claude`: run `/model <alias>`. Lane `glm-headless`: run the exact command below.
|
|
293
310
|
**Milestone:** M1 *(omit on plans without milestones)*
|
|
294
|
-
**Model:** <
|
|
311
|
+
**Model:** <model>, effort <low|medium|high> — <one-line rationale tied to this phase's difficulty> *(default: `caddis_routing.py session --role <role>`; the orchestrator runs on the `orchestrator` row, plans and designs on the `plan-writer` row)*
|
|
295
312
|
**Lane:** claude — this session | glm-headless — `claude-glm -p "/caddis:implement <this plan's path> — Phase 1 only"`
|
|
296
313
|
**Type:** backend | hard | ui | tests | docs *(required when the Lane runs through caddis_lanes.py)*
|
|
297
314
|
**Execution:** inline | per-task *(the rule in Step 2; per-task phases list their tasks below)*
|
|
298
315
|
**Session:** continue | **fresh** (start a new session for this phase — note why: lane change / heavy context)
|
|
316
|
+
**Programme phase:** yes — <why> *(omit unless the phase breaks the size rule: one agy card ≤ 6 files; one phase ≤ 12 files and ≤ 6 cards or tasks)*
|
|
317
|
+
**Depends on:** Phase <x> *(optional: write it only when this phase does NOT need the phase before it; name the phase it does need, or "nothing". It is not a wave marker: the executor picks waves at run time, `/caddis:implement` "Waves")*
|
|
299
318
|
**Risk:** high — token-verification seam; a wrong answer here is a silent auth bypass *(omit this line when normal)*
|
|
300
319
|
**Goal:** <one sentence>
|
|
301
320
|
**Touches:** `<files>`
|
|
@@ -340,12 +359,13 @@ Three rules: one attempt, one review.
|
|
|
340
359
|
review between tasks. One cross-review, by one other vendor, runs at the end of the phase.
|
|
341
360
|
- **Session boundaries:** the executor WRITES the handoff (durable `relay.md` + Tracker) after any
|
|
342
361
|
phase that ends a sitting — it performs the work, it does not suggest the command. Start a FRESH
|
|
343
|
-
session (or `/clear`) before any phase marked `Session: fresh`, before a lane change, or
|
|
344
|
-
context
|
|
362
|
+
session (or `/clear`) before any phase marked `Session: fresh`, before a lane change, or when the
|
|
363
|
+
context rule says so (Session rules above: checkpoint above 200k at a card end, the full handoff at a
|
|
364
|
+
phase end). Resume with exactly: `read <this plan's path> and implement the next ⏳ phase`.
|
|
345
365
|
- **Run to a boundary, not to a phase.** The executor implements phase after phase, committing each,
|
|
346
366
|
and stops only at a marked boundary. Do not plan a stop after every phase — that is the friction
|
|
347
367
|
this structure exists to remove.
|
|
348
|
-
- **The
|
|
368
|
+
- **The five halts, and nothing else:**
|
|
349
369
|
1. **A milestone boundary** — its `Gate:` passed and it is ready to ship.
|
|
350
370
|
2. **A phase marked `Session: fresh`** — context is heavy or the work changes shape.
|
|
351
371
|
3. **After a `risk: high` phase** — *after*, never before. The phase is executed and committed
|
|
@@ -358,6 +378,9 @@ Three rules: one attempt, one review.
|
|
|
358
378
|
on it. A headless marker (`CADDIS_HEADLESS=1`) alone does not lift the halt.
|
|
359
379
|
4. **A failed or blocked phase** — tests red, exit gate unmet, or the plan turned out wrong. Stop;
|
|
360
380
|
do not build on it.
|
|
381
|
+
5. **The checkpoint after the 200k warning** — at a card end, when 2 or more cards are left in the
|
|
382
|
+
phase (`/caddis:handoff`, "Checkpoint"). Interactive sessions only: a headless session never
|
|
383
|
+
checkpoints; at 280k it ends `BLOCKED context <n>`.
|
|
361
384
|
- **A lane change is NOT a halt.** `/caddis:implement` spawns the assigned lane itself and verifies
|
|
362
385
|
the result. It used to need a human only because the routing was inert.
|
|
363
386
|
- **At every halt, leave both:** the executor PERFORMS the handoff (writes `relay.md`, updates the
|
|
@@ -399,6 +422,11 @@ Status words (one vocabulary, `scripts/caddis_status.py`): done is `done`, `merg
|
|
|
399
422
|
`in progress`, `blocked` and `moved` name the other states; anything else (`not started`, `☐`) is to do. A cell
|
|
400
423
|
that says `pending` is never done.
|
|
401
424
|
|
|
425
|
+
## Per-symbol grep preflight (before the plan is committed)
|
|
426
|
+
Check every name a card gives: each symbol, file, line number and CSS variable. Use one grep per name
|
|
427
|
+
(Grep, or `git grep -n`) before you commit the plan. Fix the card when a name or a line number differs.
|
|
428
|
+
The orchestrator re-checks a card's names the same way, one grep per name, before it sends the card.
|
|
429
|
+
|
|
402
430
|
## Plan quality gate — local-coder ready (MANDATORY)
|
|
403
431
|
The plan must be executable by a **low-capability local coder model** (the planner→coder handoff: a
|
|
404
432
|
strong model plans, a cheaper/local model implements). The plan carries the intelligence; the coder
|
|
@@ -34,7 +34,7 @@ mode.
|
|
|
34
34
|
## Step 2 — check this session's name before loading anything
|
|
35
35
|
|
|
36
36
|
Run `ListAgents`. Its header line says `This session is <name>`; that is your name. The sheet row's
|
|
37
|
-
Start line already names the session: `claude --name <expected> "/caddis:fleet-open <role>"`, where
|
|
37
|
+
Start line already names the session: `cd "<folder>"; claude --model <model> --effort <effort> --name <expected> "/caddis:fleet-open <role>"`, where
|
|
38
38
|
`<expected>` is `new_name` of the role at the sheet's hour.
|
|
39
39
|
|
|
40
40
|
- `<name>` equals `<expected>` → go on.
|
|
@@ -73,6 +73,70 @@ Step 8 prints all 12 in this order. Never drop a row from the report, even when
|
|
|
73
73
|
`caddis_tidy.py --prune --apply` on its own, in any checkout (nor `--prune --temp --apply`); only the user can ask for it (Step 6b). In a
|
|
74
74
|
shared checkout the report also lists every tracked file Step 1 changed, under `Docs PR needed:`.
|
|
75
75
|
|
|
76
|
+
## Checkpoint (mid-phase, between cards)
|
|
77
|
+
The handoff has two tiers. The **full** tier is this whole command. The **checkpoint** tier is a cheap
|
|
78
|
+
mid-phase handoff: two script calls, about 3 model calls. It writes the relay and the tasks file and prints
|
|
79
|
+
the RESUME block. The next full handoff does the rest.
|
|
80
|
+
|
|
81
|
+
**When to checkpoint.** At a card end (or a task end), when one of these is true:
|
|
82
|
+
- The context_size hook printed the 200k warning, and 2 or more cards are left in the phase. When 1 card
|
|
83
|
+
or less is left, finish the phase and run the full handoff instead.
|
|
84
|
+
- The hook printed the 280k stop line. Start no new card. Checkpoint at the first moment no agent or
|
|
85
|
+
background command runs.
|
|
86
|
+
- You stop for more than 1 hour and the conversation is over 100k tokens.
|
|
87
|
+
|
|
88
|
+
**In a wave** (`/caddis:implement`, "Waves"), the card end is the safe point (rule 4): no child runs, and
|
|
89
|
+
each finished child is recorded. Checkpoint only there, and never `/clear` while a child runs. The relay
|
|
90
|
+
lists each wave member's phase, worktree, branch, last commit and next card.
|
|
91
|
+
|
|
92
|
+
**When not to checkpoint.** Run the full handoff, or do what the refusal says:
|
|
93
|
+
- A headless session (`CADDIS_HEADLESS` set). The script refuses (exit 1):
|
|
94
|
+
`CHECKPOINT: refused headless: return BLOCKED with your state`. An Agent-tool subagent also never runs
|
|
95
|
+
it; it returns `BLOCKED: <cards done, commits, next card>`.
|
|
96
|
+
- The coordinator's relay. The script refuses (exit 1): `CHECKPOINT: coordinator: run /caddis:handoff`.
|
|
97
|
+
It also refuses when it cannot run the coordinator check:
|
|
98
|
+
`CHECKPOINT: cannot tell if <name> is the coordinator relay (<why>): run /caddis:handoff`.
|
|
99
|
+
- A fleet close (`FLEET CLOSE from <coordinator>`). Always run the full handoff with `--fleet` (Step 9).
|
|
100
|
+
- An agent or a background command still runs. Finish without `--idle` refuses (exit 1):
|
|
101
|
+
`CHECKPOINT: wait until no agent or background command runs`.
|
|
102
|
+
|
|
103
|
+
**The two commands.**
|
|
104
|
+
1. **Prepare.** It reads the relay hash before you compose the new relay:
|
|
105
|
+
```
|
|
106
|
+
python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_handoff.py" checkpoint --session-id <session-id> --plan <plan> --phase <N>
|
|
107
|
+
```
|
|
108
|
+
(Source checkout: `scripts/caddis_handoff.py`. Add `--name <name>` when you know the workstream.) It
|
|
109
|
+
prints `workstream:`, `relay:`, `hash:`, `shared:`, `tasks:`, `budget: 4000` and `next:`.
|
|
110
|
+
2. **Finish.** Write the new relay to a temp file with the Write tool (never a heredoc). Then run the
|
|
111
|
+
`next:` command as printed. Replace `<tmp>` with the temp file path. Set `--kt` to `done` or
|
|
112
|
+
`skipped:<reason>`. Keep `--idle` only when no agent or background command runs.
|
|
113
|
+
|
|
114
|
+
**What you write.** Only three things; the script does the rest:
|
|
115
|
+
- **The relay text.** Use the Step 3 format. It holds the current state only, and the Done-pruning rules
|
|
116
|
+
(Rules) apply. `## Next step` names the next card exactly. Keep it under 4,000 characters.
|
|
117
|
+
- **The Tracker Edit.** Set the phase's Tracker row to `in progress` and name the last card done. Finish
|
|
118
|
+
fails row 2 when the row does not say `in progress`. Do not commit the plan file: finish prints
|
|
119
|
+
`plan file modified, not committed`, and a "no stray files" card check exempts the plan path. In a
|
|
120
|
+
shared checkout (Step 0), make no Tracker edit: finish prints row 2 as
|
|
121
|
+
`skipped: shared checkout (card state is in the relay)`, so the checkpoint changes no tracked file.
|
|
122
|
+
- **The knowledge-transfer decision.** When a root cause, a workaround or a rejected approach is new since
|
|
123
|
+
the last handoff, dispatch the `knowledge-transfer` subagent (Step 1) first, then pass `--kt done`.
|
|
124
|
+
Else pass `--kt skipped:<reason>`.
|
|
125
|
+
|
|
126
|
+
**What finish prints.** `=== CHECKPOINT CHECKLIST ===` with the same 12 rows as Step 8, in the same order.
|
|
127
|
+
Rows 5, 6, 8, 9, 10 and 12 print `skipped: checkpoint tier`. Then it prints the RESUME block (Step 9) as its
|
|
128
|
+
last output. Print that block as it is, with nothing after it, then ask the owner for `/clear`.
|
|
129
|
+
|
|
130
|
+
**When finish fails** (exit 1):
|
|
131
|
+
- `CHECKPOINT: row 3 relay failed`: the relay is NOT written. A peer changed the relay after prepare: the
|
|
132
|
+
script prints the diff and writes nothing. Run prepare again for the new hash, merge by hand, and finish
|
|
133
|
+
again. Never force it.
|
|
134
|
+
- `CHECKPOINT: handover-check failed`: the relay is written, but it names a missing path or is over 4,000
|
|
135
|
+
characters. There is no RESUME block. Fix the relay, then run prepare and finish again.
|
|
136
|
+
- `ERROR after relay write: <reason>`: the relay is written (`relay written:` names it), but a later step
|
|
137
|
+
failed. Finish prints the RESUME block when it can. When there is none, resume from the relay path; do not
|
|
138
|
+
write the block by hand.
|
|
139
|
+
|
|
76
140
|
## Step 1 — capture learnings FIRST (knowledge-transfer)
|
|
77
141
|
**Before** gathering git signals or writing relay.md, decide on `knowledge-transfer` — and the default
|
|
78
142
|
is to run it.
|
|
@@ -247,7 +311,9 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/session_state.py" tasks-file --session-id
|
|
|
247
311
|
```
|
|
248
312
|
It reads the `## Tasks` table of `.caddis/session-state/<session-id>.md`, keeps the rows that are
|
|
249
313
|
not `done` or `deleted`, and prints `[TASKS] <n> open task(s) -> <path>` or `[TASKS] none open`
|
|
250
|
-
(with no open task it deletes an old `.caddis/relay/<name>.tasks.md`).
|
|
314
|
+
(with no open task it deletes an old `.caddis/relay/<name>.tasks.md`). The state file is in the
|
|
315
|
+
folder the session started in; if that is not the work repo, add `--state-root <start folder>`
|
|
316
|
+
(the tasks file still goes under `--root`). A missing state file prints the path it tried. When it wrote a file, the
|
|
251
317
|
relay's resume prompt must hold the sentence
|
|
252
318
|
`Load every row of .caddis/relay/<name>.tasks.md with TaskCreate.`: Step 5 blocks a relay whose
|
|
253
319
|
tasks file exists and is not named. If you wrote the relay before running this, rewrite it with
|
|
@@ -435,13 +501,17 @@ python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_fleet.py" resume-block --name <name
|
|
|
435
501
|
the session name (`session-state/<session-id>.name` when `whoami` wrote it, else the first 8 characters of
|
|
436
502
|
the id). It prints, and you print its output as it is, with nothing after it:
|
|
437
503
|
```
|
|
504
|
+
Model for next session: <model>, effort <effort>
|
|
438
505
|
=== RESUME ===
|
|
439
506
|
Session: <session name> (<session id>)
|
|
440
507
|
Workstream: <name>
|
|
508
|
+
Repo: <absolute repo root>
|
|
441
509
|
<the resume prompt, in a fenced block>
|
|
442
510
|
Start line:
|
|
443
|
-
claude --name <role>-<MMDD>-<HH> '<the resume prompt on one line> <the announce sentence>'
|
|
511
|
+
cd "<absolute repo root>"; claude --model <model> --effort <effort> --name <role>-<MMDD>-<HH> '<the resume prompt on one line> <the announce sentence>'
|
|
444
512
|
```
|
|
513
|
+
`<model>` and `<effort>` come from `caddis_routing.py session` (Rules, "Model for the next session").
|
|
514
|
+
The `cd` makes the relay's repo-relative paths work from any terminal folder (`;`, not `&&`: Windows PowerShell 5.1 has no `&&`).
|
|
445
515
|
- **The announce sentence.** In a normal handoff the one-line start line also ends with a sentence that tells
|
|
446
516
|
the new session to run `caddis_fleet.py whoami` with its new name, then `caddis_fleet.py peers`, and to send
|
|
447
517
|
each named live peer in the same repo (the checkout and its worktrees) one `SendMessage`:
|
|
@@ -458,11 +528,16 @@ claude --name <role>-<MMDD>-<HH> '<the resume prompt on one line> <the announce
|
|
|
458
528
|
`--role <role>` to set another.
|
|
459
529
|
|
|
460
530
|
## Rules
|
|
461
|
-
- **
|
|
462
|
-
the
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
531
|
+
- **Context rule.** Above 200k: checkpoint at the next card end when 2 or more cards are left; else finish
|
|
532
|
+
the phase and run the full handoff. At 280k: checkpoint at the first moment no agent or background command
|
|
533
|
+
runs. Then ask the owner for `/clear`. Each turn re-reads the whole conversation, so a long session costs
|
|
534
|
+
more with every turn. The context_size hook prints the exact command at 200k and at 280k ("Checkpoint" above).
|
|
535
|
+
- **Model for the next session.** Take the model and effort from the session table:
|
|
536
|
+
`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_routing.py" session --role <role>` prints `<model> <effort>`.
|
|
537
|
+
The role is `orchestrator` to run an approved plan and `plan-writer` to write a plan or design.
|
|
538
|
+
`resume-block` (Step 9) reads the same table: it prints `Model for next session: <model>, effort <effort>`
|
|
539
|
+
as its first line and puts `--model <model> --effort <effort>` in the Start line. Pass `--role plan-writer`
|
|
540
|
+
for plan or design work. Do not print a second model line.
|
|
466
541
|
- **One next action, by priority ladder.** `## Next step` names exactly ONE action — not a menu. Pick it in
|
|
467
542
|
order: (1) interrupted mid-phase work → finish + commit it; else (2) the active plan's next not-started
|
|
468
543
|
phase; else (3) the top open question/decision. Everything else is context, not the next step.
|
|
@@ -61,9 +61,30 @@ Measured 24-25 Oct 2026: about 60% of usage was cache re-reads in long Opus main
|
|
|
61
61
|
and 95-154 turns per session were started by background events. Each turn re-reads the whole conversation.
|
|
62
62
|
- **Small context.** Ask each subagent for a reply under about 200 words. Full reports go to files; read a
|
|
63
63
|
file only for the part you need. Never paste or tail a large output.
|
|
64
|
-
- **
|
|
65
|
-
|
|
66
|
-
|
|
64
|
+
- **Context rule.** Above 200k: checkpoint at the next card end when 2 or more cards are left; else finish
|
|
65
|
+
the phase and run the full handoff. At 280k: checkpoint at the first moment no agent or background command
|
|
66
|
+
runs. The checkpoint is the "Checkpoint" section of `/caddis:handoff`; the context_size hook prints its
|
|
67
|
+
exact command at 200k and at 280k. At each phase end, write the full handoff yourself (see "At every halt"
|
|
68
|
+
below). **Headless (`CADDIS_HEADLESS` set): never checkpoint** (the script refuses). At 280k, start no new
|
|
69
|
+
card, commit only finished cards, write `BLOCKED context <n>` and your state (cards done, commits, next
|
|
70
|
+
card) in the review file, and end with the JSON block.
|
|
71
|
+
- **Unattended runs.** The mode is on when the marker file `~/.caddis/UNATTENDED` exists and is under 16 hours
|
|
72
|
+
old, or when the env variable `CADDIS_UNATTENDED` is set. Do not stop and do not ask for /clear. At the WARN
|
|
73
|
+
card end and at FORCE, run the checkpoint, then go on with the next card. Auto-compact brings the relay back
|
|
74
|
+
into the session. The limit is `CADDIS_UNATTENDED_MAX_FORCE` (default 6 FORCE cycles). After that, write the
|
|
75
|
+
relay and stop. For overnight work, prefer `caddis_roadmap_run.py --plan <slug>`: the runner starts a fresh
|
|
76
|
+
session for the same batch.
|
|
77
|
+
**Owner rule (28 Oct):** when the owner says "unattended", "overnight" or "I will be gone", ask ALL open
|
|
78
|
+
questions BEFORE the run starts. Use one `AskUserQuestion` round with every open choice (merge policy, PR
|
|
79
|
+
handling, spend limit, pending owner gates, any other decision the plan leaves to the owner). Make each
|
|
80
|
+
question self-contained. Start the run only after the answers. If a question comes up DURING the run, park
|
|
81
|
+
the work it blocks in the relay, go on with work that does not need the answer, and never stop the whole run
|
|
82
|
+
for it.
|
|
83
|
+
- **Model.** Take the model and effort from the session table:
|
|
84
|
+
`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_routing.py" session --role orchestrator` prints `<model> <effort>`
|
|
85
|
+
(source checkout: `claude-harness/scripts/caddis_routing.py`). Opus stays for plans, designs and
|
|
86
|
+
critical-code subagents (`plan-writer`, `critical-phase`).
|
|
87
|
+
- **Escalation.** Escalate to Opus through a SMALL subagent (by-reference brief, reply ≤ 10 lines), never `/model opus` mid-session (the prompt cache is per model, so a switch at 200k re-writes the whole cache), when: a card fails again after its one fix card; a measurement fails a rule (isolate the cause first, then give the owner options); a plan amendment changes the design, not only facts; a risk-high phase reaches review. A fresh Opus session only to write a new plan or a redesign.
|
|
67
88
|
- **One phase review.** Run `/caddis:cross-review --range <base>..HEAD` (one other vendor; agy Argon by default).
|
|
68
89
|
Never use a Claude reviewer subagent. Exception: every other-vendor provider failed. Then say so in the review file.
|
|
69
90
|
- **Mechanical tasks** (literal tests, moves, deletes, renames) go to agy through
|
|
@@ -71,6 +92,58 @@ and 95-154 turns per session were started by background events. Each turn re-rea
|
|
|
71
92
|
- **Fewer wake-ups.** Run one `ci-watch` per PR head. When it times out on a queued run, watch that run once
|
|
72
93
|
with `ci-watch --run <id>`; do not start a new PR watch. Write no "still waiting" turns.
|
|
73
94
|
|
|
95
|
+
## Waves
|
|
96
|
+
|
|
97
|
+
A wave runs up to 3 phases at the same time. Pick it at run time; the plan has no wave marker. In a wave,
|
|
98
|
+
the orchestrator's context holds its own briefs, each child's reply and the gate output it runs. It does
|
|
99
|
+
not hold the child's work. So these rules keep briefs and replies small:
|
|
100
|
+
1. **Brief by reference:** "read <plan>, Card rules, then Phase N card B". Never paste card text into a
|
|
101
|
+
prompt.
|
|
102
|
+
2. **Reply at most 10 lines:** status, commit, the gate's result line, the report path. The full report goes
|
|
103
|
+
to a file outside every worktree (the orchestrator scratchpad `wave-<id>/p<N>.md`, or the lane packet in
|
|
104
|
+
`.caddis/orchestrator/lane-runs/`). An untracked file in a worktree blocks `git worktree remove`.
|
|
105
|
+
3. **Wave:** at most 3 phases with disjoint `Files:`, started together, one worktree each (the default cap
|
|
106
|
+
is 3 lanes, and there are 3 CI runners). A child gets ONE card per dispatch. The size rule (6 files per
|
|
107
|
+
agy card; 12 files and 6 cards per phase) applies per phase and per card, not per wave.
|
|
108
|
+
4. **Safe point:** no child runs, and each finished child is recorded (Tracker Notes or relay). Checkpoint
|
|
109
|
+
and `/clear` only at a safe point. After the 200k warning: the next safe point after a card end (normally
|
|
110
|
+
the wave end). At 280k: start no new card, wait for the running children (each only up to its time
|
|
111
|
+
limit, rule 10), then checkpoint. Never `/clear` while a child runs.
|
|
112
|
+
5. **Children never write the relay** and never run a handoff or a checkpoint: only the orchestrator writes
|
|
113
|
+
the relay. The script refuses a headless child; the brief says it for an Agent-tool subagent. So
|
|
114
|
+
`put --expected-hash` has one writer per workstream. A child at its own limit returns
|
|
115
|
+
`BLOCKED: <cards done, commits, next card>`. The context_size hook does not measure subagents (it reads
|
|
116
|
+
the main thread only); a headless child session gets the headless 280k text.
|
|
117
|
+
6. **Worktrees:** make each from the feature-branch head at `$CADDIS_WORKTREE_ROOT/<repo>/<plan>-p<N>`,
|
|
118
|
+
else `<parent of the main checkout>/.worktrees/<repo>/<plan>-p<N>` (or use `caddis_lanes.py run`, which
|
|
119
|
+
makes and records its own). Record it with
|
|
120
|
+
`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_created.py" record --path <path> --kind worktree --purpose "wave <id> phase <N>"`,
|
|
121
|
+
and remove it after the merge. Every child shell command starts in its own worktree.
|
|
122
|
+
7. **Merge:** one member at a time into the feature branch. Run the whole test folder after each merge, and
|
|
123
|
+
the phase gates. A conflict stops that member only.
|
|
124
|
+
8. **Cost:** wave cost is the sum of its members, each on the cheapest fitting model from the session table
|
|
125
|
+
(`caddis_routing.py session`). Before the wave, `caddis_spend.py status` headroom must cover the members
|
|
126
|
+
× the per-call reserve. Exit 75 means "not run", not "failed".
|
|
127
|
+
9. **No plan-time marker.** Pick the wave from the CURRENT `Files:` lists: at most 3 phases, disjoint, one
|
|
128
|
+
worktree each. Safety comes from this run-time check and the whole test folder after each merge, not
|
|
129
|
+
from the plan: phases often touch files outside their `Files:`. A plan adds only an optional
|
|
130
|
+
`**Depends on:** Phase <x>` line, when a phase does NOT need the phase before it.
|
|
131
|
+
10. **Child time limit and orphans.** Every brief states a time limit: 20 minutes for a card (the same as the
|
|
132
|
+
agy `--print-timeout`), 10 minutes for a read-only child. At the limit plus 2 minutes with no reply, stop
|
|
133
|
+
the child (`TaskStop`) and run the orphan check in its worktree: `git status --short` and
|
|
134
|
+
`git log <feature-head>..HEAD --oneline`. Then:
|
|
135
|
+
- (a) A commit exists and the card gate passes in that worktree: keep it; the card is done.
|
|
136
|
+
- (b) A commit exists and the gate fails, or the tree is dirty with no commit: write
|
|
137
|
+
`BLOCKED: orphan <worktree> <branch> <state>` in the Tracker Notes. Do NOT delete the worktree.
|
|
138
|
+
Re-dispatch the card ONCE from a fresh worktree off the feature head.
|
|
139
|
+
- (c) Nothing changed: re-dispatch the card once, the same way.
|
|
140
|
+
A second failure of the same card stops the wave, and the orchestrator asks the owner. The 10-line reply
|
|
141
|
+
cap stays: on a failure, read the child's full report FILE (rule 2), not a longer reply. A child that
|
|
142
|
+
dies leaves its worktree. The orchestrator removes it after the merge, or the owner decides; the child
|
|
143
|
+
never does.
|
|
144
|
+
|
|
145
|
+
A headless session (`CADDIS_HEADLESS` set) never starts a wave: it is a wave member at most.
|
|
146
|
+
|
|
74
147
|
## Three rules: one attempt, one review
|
|
75
148
|
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).
|
|
76
149
|
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.
|
|
@@ -284,9 +357,16 @@ report — do not redo completed work.
|
|
|
284
357
|
violated), **stop there**: leave later phases untouched, record the blocker in the review file, mark the
|
|
285
358
|
Tracker row `blocked`, and report honestly with `"tests":"failed"` — never fake completion.
|
|
286
359
|
|
|
287
|
-
**3b. Halt only at a boundary.** Implement phase after phase, committing each. Stop for exactly
|
|
360
|
+
**3b. Halt only at a boundary.** Implement phase after phase, committing each. Stop for exactly five
|
|
288
361
|
reasons — a **milestone boundary**, a phase marked `Session: fresh`, **after** a `risk: high` phase,
|
|
289
|
-
|
|
362
|
+
a **failed/blocked** phase, or (interactive only) **the checkpoint after the 200k warning** at a card end
|
|
363
|
+
(the context rule above). A lane change is not one of them: you spawn the lane yourself (Step 1).
|
|
364
|
+
|
|
365
|
+
**Unattended mode** (see "Unattended runs"): the 200k-checkpoint halt and the `Session: fresh` halt do not apply
|
|
366
|
+
in unattended mode. Run the checkpoint, then go on. After a `risk: high` phase, run `/caddis:cross-review` by
|
|
367
|
+
tier (owner decision OG3 (c), `.caddis/decisions/2026-10-28-unattended-runs.md`) and go on when it has no
|
|
368
|
+
blocking finding. If it has one, write one fix card, then halt. A milestone boundary and a failed/blocked phase
|
|
369
|
+
still halt.
|
|
290
370
|
|
|
291
371
|
The `risk: high` halt is deliberately *after*, not before. Execute and commit the phase normally; the
|
|
292
372
|
halt exists to stop the **next** phase building on it before a human has looked, so the blast radius
|
|
@@ -355,7 +435,7 @@ runs `caddis_tidy.py --check` on the PR's files and stops on a plan whose Tracke
|
|
|
355
435
|
status is not, so a skipped tidy is caught before the PR opens.
|
|
356
436
|
|
|
357
437
|
**5. Write a concise review file** to `.caddis/reviews/<slug>.md`, where `<slug>` is the plan file's
|
|
358
|
-
name without `.md`. Create `.caddis/reviews/` if needed.
|
|
438
|
+
name without `.md`. Create `.caddis/reviews/` if needed. Never put a review in `.caddis/parking-lot/`: park only follow-up items, one item per file, `type: parking-lot`.
|
|
359
439
|
Keep it short and scannable — this is what the human reviewer reads before merging the branch:
|
|
360
440
|
|
|
361
441
|
```markdown
|
|
@@ -67,6 +67,7 @@ Park it only if it is work **we** will do later. Redirect these instead, and say
|
|
|
67
67
|
| An interrupted task you will come back to this session | `/caddis:digress` |
|
|
68
68
|
| Blocked on a person outside this repo | `.caddis/comms/` + its `register.md` |
|
|
69
69
|
| A fact about the environment, not a task | the KB (`/caddis:kb`) |
|
|
70
|
+
| A review (findings, a verdict) | `.caddis/reviews/`, `type: review`; park only each item to do later, one per file |
|
|
70
71
|
|
|
71
72
|
### Step 2 — do not duplicate
|
|
72
73
|
|
|
@@ -302,6 +302,7 @@ Produce a structured report (see Output Format below).
|
|
|
302
302
|
## Output Format
|
|
303
303
|
|
|
304
304
|
The report is written to the path specified by the invoking agent. Default: `.github/agent-docs/preflight-report.md`
|
|
305
|
+
Never write it in `.caddis/parking-lot/`: that folder holds only items to do later, one item per file, `type: parking-lot`.
|
|
305
306
|
|
|
306
307
|
Apply `.github/instructions/document-frontmatter.instructions.md` when creating or updating the report. The YAML frontmatter block must be the first content in the file. New reports require `Original Author`, `Creation Date`, and `Creating Model`; revised reports must preserve those fields and add or update `Last Author`, `Last Updated`, and `Last Model Used`.
|
|
307
308
|
|
|
@@ -23,6 +23,9 @@ The relay can be old. Before you act, compare it with the real state: the plan t
|
|
|
23
23
|
pull requests and remote branches. If they disagree, trust the real state. Fix the relay and the tracker. Do not build on a
|
|
24
24
|
guess.
|
|
25
25
|
|
|
26
|
+
If the relay ends `STATUS: BLOCKED context`, an earlier session of this batch ran out of context: go on from its Next
|
|
27
|
+
step; its commits are on your branch.
|
|
28
|
+
|
|
26
29
|
## 3. Pick the batch
|
|
27
30
|
|
|
28
31
|
A batch is ONE tracker phase (the first row that is not done and not blocked), or ONE named batch that the plan or the relay
|
|
@@ -64,13 +67,17 @@ STATUS: BLOCKED <owner>
|
|
|
64
67
|
STATUS: FAILED <reason>
|
|
65
68
|
```
|
|
66
69
|
|
|
70
|
+
`STATUS: BLOCKED context <n>` is a `BLOCKED` line: use it only when the context_size hook tells you to. The runner then
|
|
71
|
+
starts a fresh session for the same batch. Your relay must name the cards done, their commits and the next card. Do not
|
|
72
|
+
call PushNotification for it.
|
|
73
|
+
|
|
67
74
|
Use `STATUS: CONTINUE` only when the next batch can start with no owner input. A missing or bad line counts as FAILED.
|
|
68
75
|
An owner gate id has the form `<P>-OG<n>`: the plan's 2 to 4 capital-letter prefix (for example `PM-OG1`). Name the gate
|
|
69
76
|
in the plan's decisions with that id. Any other form is a bad line.
|
|
70
77
|
|
|
71
78
|
## 6. Notify and end
|
|
72
79
|
|
|
73
|
-
When the status is not CONTINUE
|
|
80
|
+
When the status is not CONTINUE and not `BLOCKED context`, call the `PushNotification` tool as your last action. Put the plan, the status line and the
|
|
74
81
|
next step in the message. After the call succeeds, print the line `PUSH-SENT`. The runner looks for that marker. Without it,
|
|
75
82
|
the runner sends the notification itself.
|
|
76
83
|
|
|
@@ -10,7 +10,11 @@ On that turn only, the workspace's relay doc is injected as an ephemeral step so
|
|
|
10
10
|
resumes with zero re-discovery. Every later invocation emits nothing (re-injecting the relay on every
|
|
11
11
|
turn would burn context and drown the conversation).
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Every invocation (not only the first) also marks the session `working` in its status file
|
|
14
|
+
`~/.caddis/sessions/<conversationId>.json`, which the caddis hub reads (scripts/caddis_heartbeat.py).
|
|
15
|
+
|
|
16
|
+
Stdlib-only. The relay logic is self-contained; only the optional helpers (no_window, hook_log,
|
|
17
|
+
caddis_heartbeat, repo_freshness) are imported, from the bundle's scripts/ or the source tree.
|
|
14
18
|
|
|
15
19
|
agy PreInvocation stdin (camelCase protojson):
|
|
16
20
|
{"invocationNum": 1, "initialNumSteps": N, "conversationId": "…", "workspacePaths": ["…"], …}
|
|
@@ -293,6 +297,28 @@ def _mark_injected(root, conversation):
|
|
|
293
297
|
except Exception as _exc:
|
|
294
298
|
_hook_note("agy relay injection marker", _exc, root)
|
|
295
299
|
|
|
300
|
+
|
|
301
|
+
def _status_beat(data, status):
|
|
302
|
+
"""Write this agy session's status for the caddis hub (~/.caddis/sessions/). Never raises, never prints.
|
|
303
|
+
|
|
304
|
+
caddis_heartbeat.py ships under scripts/ in the agy bundle; in the source repo it is in
|
|
305
|
+
claude-harness/scripts/. Headless runs (review and lane runs) write nothing.
|
|
306
|
+
"""
|
|
307
|
+
try:
|
|
308
|
+
if str(os.environ.get("CADDIS_HEADLESS", "")).strip():
|
|
309
|
+
return
|
|
310
|
+
_here = os.path.dirname(os.path.abspath(__file__))
|
|
311
|
+
for _cand in (os.path.join(_here, "scripts"),
|
|
312
|
+
os.path.join(os.path.dirname(_here), "scripts")):
|
|
313
|
+
if os.path.isfile(os.path.join(_cand, "caddis_heartbeat.py")):
|
|
314
|
+
if _cand not in sys.path:
|
|
315
|
+
sys.path.insert(0, _cand)
|
|
316
|
+
break
|
|
317
|
+
import caddis_heartbeat as _hb # noqa: E402
|
|
318
|
+
_hb.agy_beat(data, status, plugin_root=_here) # the bundle's plugin.json sits beside the hook
|
|
319
|
+
except Exception as _exc:
|
|
320
|
+
_hook_note("agy session status", _exc)
|
|
321
|
+
|
|
296
322
|
def _workspace_roots(data):
|
|
297
323
|
"""Every workspace root in the payload, as a list. Empty when the payload has none.
|
|
298
324
|
|
|
@@ -325,6 +351,8 @@ def main() -> None:
|
|
|
325
351
|
return
|
|
326
352
|
if not isinstance(data, dict):
|
|
327
353
|
return
|
|
354
|
+
# Every invocation: the session is working (the hub's session list). Before the first-turn gate.
|
|
355
|
+
_status_beat(data, "working")
|
|
328
356
|
# SessionStart equivalent: the FIRST invocation only (agy 0-indexes invocationNum, so the
|
|
329
357
|
# first turn is 0, not 1). Anything else (or an unparseable invocationNum) injects nothing.
|
|
330
358
|
try:
|
|
@@ -110,6 +110,7 @@ change, so a batch does not report the others as missing.
|
|
|
110
110
|
the main thread after reading the findings.
|
|
111
111
|
- Treat exit 3/4 as blocking-unknown, never as approval (the tool is fail-closed by design).
|
|
112
112
|
- Different vendor ⇒ different style; weigh its findings on merit, don't cargo-cult them.
|
|
113
|
+
- Save review notes in `.caddis/reviews/`, never in `.caddis/parking-lot/`: that folder holds only items to do later, one item per file, `type: parking-lot` (`/caddis:park`).
|
|
113
114
|
- **Never use `find`, `Get-ChildItem -Recurse`, or any other filesystem-wide search to locate
|
|
114
115
|
`oss_review.py`.** Check only the two paths above. On Git Bash under Windows, `find /` (or any
|
|
115
116
|
search rooted at `/`) walks every mounted drive, not just the repo — it can hang or take minutes.
|
|
@@ -61,6 +61,8 @@ Check for:
|
|
|
61
61
|
|
|
62
62
|
## Review Output Format
|
|
63
63
|
|
|
64
|
+
In a caddis repo, save a review note in `.caddis/reviews/`, never in `.caddis/parking-lot/`: that folder holds only items to do later, one item per file, `type: parking-lot`.
|
|
65
|
+
|
|
64
66
|
```markdown
|
|
65
67
|
## Code Review Summary
|
|
66
68
|
|
|
@@ -302,6 +302,7 @@ Produce a structured report (see Output Format below).
|
|
|
302
302
|
## Output Format
|
|
303
303
|
|
|
304
304
|
The report is written to the path specified by the invoking agent. Default: `.github/agent-docs/preflight-report.md`
|
|
305
|
+
Never write it in `.caddis/parking-lot/`: that folder holds only items to do later, one item per file, `type: parking-lot`.
|
|
305
306
|
|
|
306
307
|
Apply `.github/instructions/document-frontmatter.instructions.md` when creating or updating the report. The YAML frontmatter block must be the first content in the file. New reports require `Original Author`, `Creation Date`, and `Creating Model`; revised reports must preserve those fields and add or update `Last Author`, `Last Updated`, and `Last Model Used`.
|
|
307
308
|
|