Guide ยท sdlc-light only
Plan to spec
This guide follows one change in the sdlc-light domain: a rate limit for a login
endpoint. It moves from idea to plan to evidence, and ends as a fact in specs/.
Other domains use other pillars and gates; see their domain profiles.
1. Capture the idea
Ask your agent to use cumaru-explore:
Explore a rate limit for the login endpoint. It creates exploring/login-rate-limit/index.md. Explorations are never loaded by
default and carry no commitment.
2. Promote it to a plan
Promote the login-rate-limit exploration to a plan. cumaru-explore hands off to cumaru-plan, which creates plans/maintenance-login-rate-limit/index.md. Without a tracker key, plan IDs use the maintenance- prefix. The plan holds:
scope:the spec areas it touches, such asauth/index.md;- acceptance criteria in EARS or RFC 2119;
- one
t<N>.mdfile per task, with its files and dependencies.
The exploration is then removed, or first copied into the plan as exploration.md when
it is worth keeping.
3. Implement with evidence
For each task, the agent implements the change and writes handoff-t<N>.md with
the files touched and the verification it ran. At the end, it writes delta-draft.md: the spec claims the plan adds, changes, or removes.
4. Close and absorb
Close the maintenance-login-rate-limit plan. cumaru-absorb refuses to start unless every gate passes:
- every task is
doneand has a handoff with evidence; - every acceptance criterion is verified against the implementation. A status label, a clean doctor, or a commit is not proof;
- the
gitopt-in skill is installed and you authorized Git writes; - every plan file is committed, with no diff and no untracked or ignored file.
If a gate fails, the plan stays intact. Discarding a plan needs a separate decision from you.
5. What absorption does
- Finds the spec file that owns each claim with
cumaru tree specs. - Writes the claims, reconciles them with the criteria, and runs
cumaru doctor. - Commits the specs and the complete plan as the recovery point.
- Removes the plan and any consumed exploration that remains, then commits the cleanup.
cumaru fs plans/maintenance-login-rate-limit remove If cleanup fails, the recovery commit from step 3 still holds everything. Afterward, specs/auth/ states the rate limit as current behavior, and git log links back
to the plan.
Sources: cumaru-explore, cumaru-plan, cumaru-absorb, templates. The rate-limit example and prompts are illustrations from this site.