Build from a prompt

cascade prompt is the simplest on-ramp. No meeting recording, no ticket, no review board. Type what you want, and Cascade runs the full pipeline (plan, code, test, commit, push, open a PR).

It is the right entry point for small, well-scoped work. For larger work that needs collaborative refinement, prefer a tracker ticket or a meeting transcript.

When prompts are the right tool

Reach for cascade prompt when:

• The change is small enough that the requirements fit in a sentence or two
• You already know exactly what you want, technically
• The work is too small to justify creating a ticket
• You are doing cleanup, refactoring, or maintenance
• You are running an experiment or trying something throwaway

Reach for a different on-ramp when:

• Requirements need discussion before they are ready (use a meeting transcript)
• The work is already captured in your team’s tracker (use cascade ticket)
• The change touches more than ~5 files (consider breaking it into stories)
• You need stakeholder review before code gets written (use the review board)

Basic usage

cascade prompt "Add a /health endpoint that returns {'status': 'ok', 'version': version}"

Cascade treats the prompt as an automatically-approved story and runs the full pipeline:

==> [story-prompt-20260925-103045] Add a /health endpoint...
  ✓ plan: 2 file(s) to change
  ✓ code: 2 file(s) generated
  ✓ branch: cascade/add-a-health-endpoint
  ✓ apply: 2 file(s) written
  ✓ install: ok
  ✓ test: passed (43 passed in 0.19s)
  ✓ commit: e4f8a2b1
  ✓ push: cascade/add-a-health-endpoint
  ✓ pr: #48
  PR: #48  https://github.com/myorg/myrepo/pull/48
  cost: $0.06 (3,210 in / 980 out tokens)

Multiline prompts

For anything beyond a sentence, use a heredoc:

cascade prompt "$(cat <<'EOF'
Add rate limiting to /api/users.

Requirements:
- 60 requests per minute per IP address
- Return 429 with Retry-After header when exceeded
- Use the existing redis client from src/clients/redis.py
- Add tests covering: under limit, at limit, over limit, header presence

Out of scope:
- Per-user (vs per-IP) limits; that comes in a later story
- Configurable limit; hardcode 60/min for now
EOF
)"

Two things to notice in that example. First, you can include “out of scope” notes; Cascade passes them to the planner verbatim and they keep scope tight. Second, mentioning the specific file path (src/clients/redis.py) tells the LLM to reuse that import rather than inventing a new client.

More detail in the prompt produces better output. Vague prompts (“make X better”) produce vague code.

How to write a good prompt

The pattern that consistently produces good results:

1. Name the thing. Be specific about endpoints, components, functions, modules.
2. Describe the behavior. What should happen on the happy path. What should happen on error paths.
3. Mention constraints. Existing files to reuse, patterns to follow, edge cases to handle.
4. Hint at success. What “done” looks like. A specific output, a status code, a particular error message.

Examples

Bad prompt	Better prompt
”Add auth"	"Add JWT auth to /api/*: middleware checks Bearer token, returns 401 on missing or invalid token, attaches user_id to the request context. Use the existing JWT secret from settings.JWT_SECRET."
"Make it faster"	"Cache the /api/dashboard response in Redis for 60 seconds, keyed by user_id. Use the redis client from src/clients/redis.py. Cache miss should still serve the live response."
"Add a button"	"Add an ‘Export CSV’ button in the toolbar of the UserList page. It calls GET /api/users/export, receives a text/csv response, and triggers a browser download named users-YYYY-MM-DD.csv."
"Fix the bug"	"Fix: User.save throws an opaque IntegrityError when an email already exists. It should catch that case and raise DuplicateEmailError with the conflicting email in the message. Keep raising IntegrityError for other constraint violations.”

Inspecting before pushing

To run the pipeline locally without pushing or opening a PR:

cascade prompt "Refactor User.save" --no-pr

This still plans, generates code, runs tests, and commits to a new branch. But it stops before push. Inspect the change with:

git log --stat HEAD~1..HEAD       # see what got committed
git diff HEAD~1 HEAD              # see the actual changes

If you like it, push manually:

git push -u origin $(git branch --show-current)
gh pr create --fill

If you do not, throw it away:

git checkout main
git branch -D cascade/refactor-user-save

Cost expectations

A typical prompt run uses 3,000 to 10,000 input tokens (the plan and code prompts include team memory, repo scan, and the prompt itself) and 500 to 3,000 output tokens. On Anthropic Claude Opus, that is roughly $0.05 to $0.20 per run. On Gemini Flash or GPT-4o-mini, an order of magnitude cheaper.

To enforce a hard ceiling:

cascade prompt "..." --max-cost 0.50

Aborts before exceeding $0.50 in cumulative LLM cost. Useful in scripts that run many prompts in a loop.

When a prompt is not enough

If you keep writing very long prompts, that is a signal to move the recurring detail somewhere it will persist. Three patterns:

1. Push detail into team memory. If every prompt says “use the redis client from src/clients/redis.py”, that belongs in team-memory/conventions.md as a convention. Cascade will read it on every run without you re-typing it. See team memory.
2. Switch to a tracker ticket. If the work is captured in your team’s process, cascade ticket jira:PROJ-123 is more discoverable and keeps the original requirement linked to the eventual PR.
3. Capture as a meeting. If the requirement came out of a design discussion, record the discussion and run cascade ingest. The transcript becomes documentation, the extracted stories become the work plan, and the review board becomes the approval gate.

Common gotchas

What happens	What to do
Generated code uses a library you do not have installed	Add the library to team memory’s conventions.md (“we use httpx, not requests”) so the planner avoids it next time. Or add it to your dependency file before re-running.
Tests pass but the change is wrong	The acceptance criteria were too loose. Rewrite the prompt with explicit “should/should not” rules. Re-run with --no-pr so you can inspect locally first.
Cascade refuses to write to a path	The path is in paths.disallowed in cascade.yaml. If it should be writable, add it to paths.allowed. Cascade defaults to allowing src/**, tests/**, docs/** only.
The branch already exists	Cascade uses the story ID in the branch name; a previous failed run left it behind. Delete it with git branch -D cascade/..., or pass a different prompt so the slug changes.

What is next

• Build from a ticket for work that originated in Jira / Linear / GitHub / Azure
• Build from a meeting for requirements that came out of a conversation
• Team memory for how to make every prompt produce better code
• CLI reference for every flag cascade prompt accepts