Build from a ticket

For ongoing development work where requirements are captured as tickets, cascade ticket is the fastest path to a PR.

Supported trackers

Tracker	Identifier format	Example
GitHub Issues	`github:owner/repo#N`	`github:myorg/myrepo#42`
Jira	`jira:KEY-N`	`jira:PROJ-123`
Linear	`linear:KEY-N`	`linear:ENG-456`
Azure DevOps Boards	`azure_devops:org/project/N`	`azure_devops:myorg/myproj/123`
GitLab Issues	`gitlab:group/project#N`	`gitlab:myteam/myrepo#42`

Set up your tracker once

# Jira (requires base URL and your email)
cascade configure issue jira \
  --token JIRA_API_TOKEN \
  --base-url https://yourcompany.atlassian.net \
  --user you@yourcompany.com

# Linear
cascade configure issue linear --token lin_api_xxx

# GitHub Issues (uses the same token as your GitHub VCS provider)
cascade configure issue github --token ghp_xxx

# Azure DevOps Boards
cascade configure issue azure_devops --token your_pat

# GitLab Issues
cascade configure issue gitlab --token glpat_xxx

Run it

cascade ticket jira:PROJ-123

Cascade fetches the ticket, converts it to a story, then runs the full pipeline: plan, code, test, PR. Output:

==> [story-jira-PROJ-123] Add cursor pagination to /api/users  (from jira:PROJ-123)
  branch:  cascade/story-jira-PROJ-123/add-cursor-pagination
  commit:  e4f8a2b1...
  install: ok
  tests:   passed (42 passed in 0.18s)
  PR:      #47  https://github.com/myorg/myrepo/pull/47

The opened PR links back to the ticket, and the PR description includes the original ticket text.

When the ticket isn’t quite right

Tracker tickets are often vague. If cascade ticket produces a plan you don’t like, you have two options:

Edit the ticket in your tracker, then re-run. Cascade pulls the latest version each time.

Use a prompt instead, supplying the missing detail directly:

cascade prompt "Implement PROJ-123: cursor pagination on /api/users with ?limit (default 50, max 200) and ?after (the last seen ID)"

Mapping tickets to repos

A ticket lives in your tracker. The repo lives separately. Cascade assumes the repo it’s currently running in (or the --repo-root you pass) is the one to build into.

cd ~/code/myrepo
cascade ticket jira:PROJ-123

Or:

cascade ticket jira:PROJ-123 --repo-root ~/code/some-other-repo

There’s no automatic mapping between trackers and repos in v0.1. If your team has a convention (Jira project keys map to specific repos), wrap Cascade in a small shell script that picks the right --repo-root.

Branching off something other than main

Default base branch is main. For teams using a develop or release/* workflow:

cascade ticket jira:PROJ-123 --base-branch develop