Your first brainstorm

In this lesson you run /c-brainstorm for the first time. Two things happen: Cadence sets up its config for the repo, and then it converges your idea into a small written stub: the first artifact of the pipeline.

What brainstorm is for

Brainstorm’s job is to turn a fuzzy thought into a written starting point through disciplined question-and-answer. It asks one question at a time, each with a recommended option, and you mostly just pick. You are never asked to draft anything from a blank page. You nod or redirect.

The feature you’ll brainstorm throughout this quickstart is deliberately tiny: a function that prints the current time in a standard format. It’s small on purpose, so the loop is fast and you can compare your result against the finished example at the end.

First run: Cadence scaffolds its config

The very first time you run /c-brainstorm in a repo that has no Cadence config, Cadence notices and offers to create one.

What is the config?

.cadence/config.yaml is a small settings file at the repo root. It tells Cadence where to keep designs and plans, whether plans default to a test-first shape, and which (if any) helper agents to consult. You answer three quick questions and Cadence writes the file. There is no separate install or setup command.

Command

/c-brainstorm a function that prints the current time

What you'll see first

No .cadence/config.yaml found in this repo or any parent.
Scaffold defaults to get started? (y/n)

Answer y, then answer three questions: where designs and plans should live (default docs/designs), whether plans should be test-first by default, and any helper agents to register (or “none”).

Then: the question-at-a-time loop

With the config written, Cadence enters the Q&A loop. Each question leads with a plain-English sentence explaining what’s being decided and why it matters right now, gives you options, and marks exactly one as Recommended so you always have a safe default.

Brainstorm the current-time function

1. Run the command with your idea

   /c-brainstorm a function that prints the current time. On a fresh repo, accept the config scaffold first (three quick questions).

2. Answer one question at a time

   Cadence asks focused questions: output format, whether to include a way to run it directly, what’s explicitly not in scope. Each has a Recommended pick. You choose; you don’t write prose.

3. Pick an approach

   Once the questions converge, Cadence proposes an approach and asks you to confirm. For this feature: a single small module with one function returning an ISO-8601 timestamp, plus a way to run it directly.

4. It writes the stub

   Cadence asks “I have enough — writing 00-overview.md. Proceed?” On yes, it writes a 00-overview.md stub under docs/designs/2026-01-15-hello-cadence/ (your date will differ) and stops. It does not auto-start the design stage.

The artifact: a 00-overview.md stub

The stub is the artifact you’ll read. It’s short and plain-English: a “What we’re building” paragraph, a one-line “Why”, the chosen approach, a proposed list of child documents, and a decisions log capturing every choice you made during the Q&A. You can open the finished version of exactly this stub in the worked example:

Where it lands

docs/designs/2026-01-15-hello-cadence/00-overview.md

What's inside

• What we’re building: a current_time_iso() function returning an ISO-8601 string.
• Why: the canonical Cadence teaching example.
• Approach: one module, one function, one test, run-directly entry.
• Doc index: the child docs design will write next.
• Decisions log: every Recommended pick you accepted.

No auto-chaining

Brainstorm writes the stub and stops. It never silently jumps into design. The handoff is explicit: it tells you to run /c-design next. That stop is the first gate.

QuizWhat single artifact does a design-brainstorm session end by writing?

1. A 00-overview.md stub
2. The full design folder
3. A plan with exact code steps
4. The implemented code

Show answer

A. A 00-overview.md stub

Brainstorm converges on an approach and writes one short stub: 00-overview.md. The full design folder is the next stage's job.

Next: Design and plan it. Grow the stub into a full design, then translate it into an exact plan.