| name | maintaining-cldk |
| description | Use when picking up an issue, bug report, small feature, or documentation gap on any codellm-devkit repository, or when triaging whether a reported problem is real. |
Maintaining CLDK
The upkeep mode of the CLDK ladder: triage → contract gate → fix loop →
propagation sweep. This is where bug fixes, small features, and docs gaps
land — the counterpart to designing-cldk-changes, which owns anything
structural. Most work enters here.
Entry Preconditions
An issue, bug report, small feature request, or docs gap already exists. No
spec and no epic are needed to start — that is the point of this mode. If
what you're holding turns out to need a design decision spanning repos, the
contract gate below routes you out.
1. Triage
Reproduce first, always — do not start editing on the strength of a
report alone:
- Analyzer bug → build a minimal fixture that exhibits it.
- SDK bug → write the failing test first.
- Docs gap → reproduce the broken render or the broken command.
Locate the affected repo(s) via references/repo-map.md. Classify what
you're holding. Triage may terminate right here with a triage verdict:
not-a-bug, duplicate, or needs-design (route to designing-cldk-changes).
If it's real and local, continue to the gate below.
If the fix changes schema v2 output (any node/edge/field, even optional
additions) or a public SDK API, STOP. This is structural work and cannot be
done here. 'Optional so it can't break anyone' is the canonical
rationalization — additive fields are still contract changes.
Report the verdict plainly, then CHECKPOINT before moving: AskUserQuestion
whether to enter designing-cldk-changes now, park it as an issue for later, or
stop. The verdict is not negotiable; the timing is the user's. Never offer
"patch it here anyway" as an option.
2. Fix Loop
Failing test first, then the fix. Follow the target repo's own CLAUDE.md
conventions (branch naming, commit style, test layout) — this mode does not
override local repo discipline, it sits on top of it.
3. Propagation Sweep
Before you consider the work done, run references/propagation-checklist.md
— sibling analyzers, SDK version pins, docs staleness, and old-behavior
fixtures elsewhere. This produces a required output, in this exact shape:
Propagation verdict: <list of follow-on repos + why> | none, because
.
Skipping this step is the second canonical failure mode of this mode, not a
lesser one than skipping the contract gate.
Terminal State
The ONLY skill you invoke after maintaining-cldk is finishing-cldk-work (or
designing-cldk-changes via the contract gate; or stop at a triage verdict if
there is nothing to fix).
Checkpoint first. Do not auto-invoke it. State what you finished, name the
next skill and why, then AskUserQuestion — proceed now, take a different path,
or stop here (see using-cldk-devtools → Transition Checkpoint). When the
contract gate fired, report the verdict plainly and still ask whether to enter
design mode now; the verdict is not up for negotiation, the timing is.
Red Flags
| Rationalization | Reality |
|---|
| "It's optional, can't break anyone." | Additive schema/API surface is still a contract change — the HARD-GATE applies regardless of optionality. |
| "Tests pass, wrap up." | Local tests passing is not the propagation sweep. Run propagation-checklist.md and produce the verdict before declaring done. |
| "That's a scope call I can just make in this conversation." | A schema-shape question is not a same-turn negotiation with whoever asked — it leaves this rung entirely, via the contract gate. |
| "This bug is local to this repo, no need to check siblings." | Siblings share the schema and the resolver patterns; a bug class rarely respects repo boundaries. The sweep exists precisely to check. |
