.ralph/specs/<name>.md.
The interview
The interview has five phases:
During the interview, the AI uses your codebase context — it reads files, searches for patterns, and explores your directory structure — to ask questions specific to your project.
Flags
string
required
Name for the feature spec. Used as the filename in
.ralph/specs/.string (repeatable)
GitHub issue number or URL to pull as context. The issue title, body, and labels are pre-loaded into the interview. Can be specified multiple times.
string (repeatable)
Additional reference URL or file path to include as context. Can be specified multiple times.
boolean
default:"false"
Headless mode — skip the interactive interview. Generates a spec directly from
--goals and any issue/context provided. Useful for scripting, CI, and agent integration.string
Feature goals description. Used with
--auto for headless spec generation.string
AI provider for spec generation. Overrides the default.
string
AI model to use for the interview.
boolean
default:"false"
Open the spec in your editor after creation.
boolean
default:"false"
Overwrite an existing spec with the same name.
Spec output
The generated spec includes:- Feature overview and goals
- Implementation steps with file paths
- Edge cases and error handling
- Testing strategy (unit + E2E)
- Acceptance criteria