> ## Documentation Index
> Fetch the complete documentation index at: https://wiggum.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# new

> Create a feature specification through an AI-guided interview.

```bash theme={null}
wiggum new <name> [options]
```

Starts an AI-guided interview to generate a detailed, project-aware feature specification. The spec is saved to `.ralph/specs/<name>.md`.

## The interview

The interview has five phases:

| Phase          | What happens                                                                   |
| -------------- | ------------------------------------------------------------------------------ |
| **Context**    | Share reference URLs, docs, files, or GitHub issues relevant to the feature    |
| **Goals**      | Describe what you want to build in plain language                              |
| **Interview**  | AI asks up to 10 clarifying questions about scope, edge cases, and constraints |
| **Generation** | Produces a detailed, implementation-ready feature spec                         |
| **Complete**   | Shows summary, saves spec to `.ralph/specs/`                                   |

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

<ParamField path="name" type="string" required>
  Name for the feature spec. Used as the filename in `.ralph/specs/`.
</ParamField>

<ParamField path="--issue" type="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.

  ```bash theme={null}
  wiggum new my-feature --issue #42 --issue #38
  ```
</ParamField>

<ParamField path="--context" type="string (repeatable)">
  Additional reference URL or file path to include as context. Can be specified multiple times.

  ```bash theme={null}
  wiggum new my-feature --context https://docs.example.com/api --context ./design-doc.md
  ```
</ParamField>

<ParamField path="--auto" type="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.

  ```bash theme={null}
  wiggum new my-feature --auto --goals "Add JWT auth middleware with refresh tokens"
  ```
</ParamField>

<ParamField path="--goals" type="string">
  Feature goals description. Used with `--auto` for headless spec generation.
</ParamField>

<ParamField path="--provider" type="string">
  AI provider for spec generation. Overrides the default.
</ParamField>

<ParamField path="--model" type="string">
  AI model to use for the interview.
</ParamField>

<ParamField path="-e, --edit" type="boolean" default="false">
  Open the spec in your editor after creation.
</ParamField>

<ParamField path="-f, --force" type="boolean" default="false">
  Overwrite an existing spec with the same name.
</ParamField>

## 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

Specs are plain markdown — agent-agnostic and compatible with Claude Code, Codex CLI, or any agent that can read files.

## Examples

<CodeGroup>
  ```bash Interactive (recommended) theme={null}
  wiggum
  # then type /new add-dark-mode in the TUI
  ```

  ```bash With GitHub issue context theme={null}
  wiggum new add-dark-mode --issue #42
  ```

  ```bash With multiple context sources theme={null}
  wiggum new add-dark-mode --issue #42 --context https://design.example.com/dark-mode
  ```

  ```bash Headless (for CI/agents) theme={null}
  wiggum new add-dark-mode --auto --goals "Add dark mode toggle with system preference detection and localStorage persistence" --issue #42
  ```

  ```bash Overwrite existing spec theme={null}
  wiggum new add-dark-mode --force
  ```
</CodeGroup>