Documentation

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 as auth/index.md;
  • acceptance criteria in EARS or RFC 2119;
  • one t<N>.md file 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 done and 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 git opt-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

  1. Finds the spec file that owns each claim with cumaru tree specs.
  2. Writes the claims, reconciles them with the criteria, and runs cumaru doctor.
  3. Commits the specs and the complete plan as the recovery point.
  4. 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.