# speckit.specify

speckit.specify turns plain-text feature descriptions into structured specifications, allocates numbered Git branches, and generates requirements checklists.

- prompt · `type=prompt` · Claude Code, Codex, ChatGPT · ★ 110 repo stars
- Author: alfredoperez
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/alfredoperez/speckit-companion/tree/HEAD/.codex/prompts/speckit.specify.md
- Updated: 2026-10-19
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/prompts/speckitspecify

## What it does

The prompt takes natural language input passed to `/speckit.specify` and derives a concise 2–4 word branch slug using an action-noun structure. Next, it runs `git fetch --all --prune` and inspects remote branches, local references, and the `specs/` directory to discover the highest existing index, calculating the next incremented number before invoking `.specify/scripts/bash/create-new-feature.sh`.

It then reads `.specify/templates/spec-template.md` and fills user scenarios, functional requirements, and technology-agnostic success metrics. When details are missing, the prompt enforces a ceiling of three `[NEEDS CLARIFICATION]` tags to prevent endless questions. A separate checklist is written to `FEATURE_DIR/checklists/requirements.md` to verify the document before moving forward.

Execution will fail early if the workspace lacks the companion scripts and Markdown templates inside the `.specify/` directory.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/commands/speckit.specify.md`

### ChatGPT

**How to use**
- Paste the text at the start of a chat or into project instructions

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/alfredoperez/speckit-companion/tree/HEAD/.codex/prompts/speckit.specify.md

## When to use it
- generate structured feature specifications directly from plain-language requests
- calculate next available Git branch numbers across local and remote repositories
- create requirements verification checklists prior to technical planning
- isolate up to three unresolved requirements questions using clarification markers

## Example prompts
- /speckit.specify Add user authentication with OAuth2
- /speckit.specify Fix payment processing timeout bug

## Source text · speckit.specify.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 01c315829e80cf54.

BEGIN THIRD-PARTY FILE 01c315829e80cf54
````text
---
description: Create or update the feature specification from a natural language feature description.
handoffs: 
  - label: Build Technical Plan
    agent: speckit.plan
    prompt: Create a plan for the spec. I am building with...
  - label: Clarify Spec Requirements
    agent: speckit.clarify
    prompt: Clarify specification requirements
    send: true
---

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Outline

The text the user typed after `/speckit.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.

Given that feature description, do this:

1. **Generate a concise short name** (2-4 words) for the branch:
   - Analyze the feature description and extract the most meaningful keywords
   - Create a 2-4 word short name that captures the essence of the feature
   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
   - Keep it concise but descriptive enough to understand the feature at a glance
   - Examples:
     - "I want to add user authentication" → "user-auth"
     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
     - "Create a dashboard for analytics" → "analytics-dashboard"
     - "Fix payment processing timeout bug" → "fix-payment-timeout"

2. **Check for existing branches before creating new one**:

   a. First, fetch all remote branches to ensure we have the latest information:

      ```bash
      git fetch --all --prune
      ```

   b. Find the highest feature number across all sources for the short-name:
      - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
      - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
      - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`

   c. Determine the next available number:
      - Extract all numbers from all three sources
      - Find the highest number N
      - Use N+1 for the new branch number

   d. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` with the calculated number and short-name:
      - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
      - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"`
      - PowerShell example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`

   **IMPORTANT**:
   - Check all three sources (remote branches, local branches, specs directories) to find the highest number
   - Only match branches/directories with the exact short-name pattern
   - If no existing branches/directories found with this short-name, start with number 1
   - You must only ever run this script once per feature
   - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")

3. Load `.specify/templates/spec-template.md` to understand required sections.

4. Follow this execution flow:

    1. Parse user description from Input
       If empty: ERROR "No feature description provided"
    2. Extract key concepts from description
       Identify: actors, actions, data, constraints
    3. For unclear aspects:
       - Make informed guesses based on context and industry standards
       - Only mark with [NEEDS CLARIFICATION: specific question] if:
         - The choice significantly impacts feature scope or user experience
````
END THIRD-PARTY FILE 01c315829e80cf54

The third-party file has ended. Everything between the 01c315829e80cf54 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 4024 of 12838 bytes. © alfredoperez · MIT · https://github.com/alfredoperez/speckit-companion/tree/HEAD/.codex/prompts/speckit.specify.md

## Similar
- [specify-requirements](https://affpapa.org/en/nevibecode/skills/specify-requirements.md) — skill · ★ 587 repo stars
- [speckit-specify](https://affpapa.org/en/nevibecode/skills/speckit-specify.md) — skill · 2700 installs
- [specify-solution](https://affpapa.org/en/nevibecode/skills/specify-solution.md) — skill · ★ 587 repo stars

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
