cdd: Command for Claude Code

Scope the next roadmap task and produce a handoff file for a fresh plan session.

This is the exploratory-session command. Run on the main worktree. Output is a handoff file that a later, isolated plan session (/cdd-plan) will consume. This session does not modify any file in the repo; the only artifact it produces is the handoff file under ~/.cdd/handoffs/cdd/.

0. Mode: roadmap-driven, intent-driven, or issue-driven

This command has one optional argument. Dispatch on its shape, trying the rows in order:

$ARGUMENTS	Mode	Branches at
empty	roadmap-driven	§3
issue or issues	issue-driven, browse	§0b
every whitespace-separated token matches the tracker's ref_pattern	issue-driven, direct	§0b
anything else	intent-driven	§3-intent

issue / issues is a fixed keyword and is checked before the pattern, so browsing stays available whatever the backend calls its references.

The argument splits on whitespace, and the direct row matches only when every token matches — one task may be sourced from several issues (/cdd-next-step 97 12). A single token is the common case and behaves exactly as before; a mixed argument (one token matching, one not) is not issue-driven and falls to intent-driven, where the whole string is read as a task prompt.

What a reference looks like is the tracker's decision, not this command's. Resolve the tracker down the ladder — project, then machine — and take the first file present:

for c in .cdd/tracker ~/.cdd/adapters/tracker; do [ -e "$c" ] && { echo "$c"; break; }; done

If one resolved, run describe and take .ref_pattern — an ERE — as the shape of a reference:

<adapter> describe    # JSON on stdout; hermetic, so it needs no network and no credentials

Use it only if the file is executable and describe exits 0, parses as JSON, reports capability tracker, and reports a contract this CDD supports (currently 1). Otherwise — not executable, a non-zero exit, unparseable, another capability, or wrong version — the adapter is installed but broken: say so in one line naming its path, and stop the command. Do not try a lower rung: an installed adapter declares which tracker this project uses, so a lower rung would answer from the wrong system. With nothing resolved there is no ref_pattern, so no argument is issue-shaped: the direct row never matches, and issue / issues still dispatches to §0b, which stops with the install line.

Resolution done only to classify the argument is otherwise silent. The line naming which rung served is printed in §0b, where a tracker call is actually made: a line in every session in every repo is noise, and noise is how a load-bearing line stops being read.

Every mode first runs §0a (checkout freshness), §1 (read context) and §2 (stale-handoff sweep); the "Branches at" column is only where the mode-specific path begins after that.

• Roadmap-driven: pick the next item off the roadmap. Run §1–§8 as written.
• Intent-driven: the task is already chosen by the user, so skip candidate proposal (§3 is replaced by §3-intent below). Use this when the user wants to start something off-roadmap rather than picking the next checkbox.
• Issue-driven: a thin front-end onto intent-driven mode — the intent text comes from a tracker item instead of being typed. §0b resolves the item, then the flow is exactly intent-driven (§1 adaptive load, §3-intent, §4 onward).

All modes converge on the same machinery from §4 onward (stale-handoff sweep in §2 runs in all of them). Do not fork the flow beyond what §0b, §1, and §3 describe.