grailautomation/specify

Spec Kit Specify

This is a user-invoked Spec Kit workflow. Treat user text after the invocation as the workflow input.

Plugin Root

Use the spec-kit plugin root when running bundled scripts. In Claude Code, ${CLAUDE_PLUGIN_ROOT} resolves to this plugin root. If that variable is unavailable, resolve the plugin root as the directory two levels above this SKILL.md.

The text after /spec-kit:specify is the feature description. Do not ask the user to repeat it unless it is empty.

User input:

$ARGUMENTS

If the input is empty, respond with: "Please provide a feature description. Example: /spec-kit:specify build a REST API for managing photo albums"

Purpose

Create a concise but executable feature spec that delivers most of Spec Kit's benefit with less ceremony. The spec must work well for existing repositories: it should describe the user-visible change and validation needs without inventing a new architecture.

Preflight

1. Inspect the current repo before creating the spec:
   • Git status and current branch, if this is a git repo
   • README.md, AGENTS.md, package/tooling files, and existing tests
   • Existing .specify/memory/project-context.md and constitution, if present
2. Run the bundled context detector if available:

   bash "${CLAUDE_PLUGIN_ROOT}/scripts/detect-project-context.sh" --write
   

   If the plugin root is not exposed by the runtime, locate the bundled script in the installed spec-kit/scripts/ directory and run that absolute path.
3. Do not initialize git. Do not switch branches unless this command is being used to start a new feature branch. If the user explicitly asks to stay on the current branch, run the create script with --no-branch.

Execution Flow

1. Create the feature directory by running the bundled script exactly once from the project root:

   bash "${CLAUDE_PLUGIN_ROOT}/scripts/create-feature.sh" $ARGUMENTS
   

   If using current-branch mode:

   bash "${CLAUDE_PLUGIN_ROOT}/scripts/create-feature.sh" --no-branch $ARGUMENTS
   

   Parse JSON for BRANCH_NAME, SPEC_FILE, FEATURE_NUM, and FEATURE_DIR. All subsequent file paths must be absolute. In current-branch or non-git mode, tell the user to set SPECIFY_FEATURE=<BRANCH_NAME> for follow-up commands unless they export it in the current shell/session.

2. Load:

   • .specify/memory/constitution.md, if present
   • .specify/memory/project-context.md, if present
   • Relevant repo docs/config discovered in preflight

3. Extract from the feature description:

   • Actors and user goals
   • User-visible behavior
   • Data/entities involved
   • Integrations, permissions, and safety constraints
   • Explicit out-of-scope items, if stated

4. Write SPEC_FILE with this structure:

# Feature Specification: [FEATURE NAME]

**Feature Branch**: `[BRANCH_NAME]`
**Created**: [today's date]
**Status**: Draft
**Repo Fit**: [one sentence naming the existing area/pattern this feature should fit]

## Overview
[1-2 paragraph summary of what this feature does and why it matters]

## User Scenarios & Acceptance Criteria

### Primary User Story
[Main user journey in plain language]

### Acceptance Scenarios
1. **Given** [initial state], **When** [action], **Then** [expected outcome]
2. **Given** [initial state], **When** [action], **Then** [expected outcome]

### Edge Cases
- [Boundary or error case]
- [Failure or permission case]

## Requirements

### Functional Requirements
- **FR-001**: System MUST [specific testable capability]
- **FR-002**: System MUST [specific testable capability]

### Non-Functional Requirements
- **NFR-001**: [Performance, reliability, observability, security, or UX criterion if material]

### Key Entities
- **[Entity]**: [What it represents, key attributes, relationships]

## Scope
- **In Scope**: [included behavior]
- **Out of Scope**: [excluded behavior]

## Review Checklist
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable
- [ ] Scope is clearly bounded
- [ ] Existing repo patterns are named or uncertainty is marked
- [ ] No implementation details beyond constraints already present in the repo
- [ ] Material unknowns are marked with `[NEEDS CLARIFICATION: specific question]`

5. Quality rules:

   • Focus on WHAT and WHY; include HOW only when the repo already imposes a constraint that must be respected.
   • Do not guess. Mark material assumptions with [NEEDS CLARIFICATION].
   • Ask clarifying questions later only when the answer would change architecture, data model, task split, tests, safety, UX, or operations.
   • Prefer fewer, higher-quality requirements over broad wish lists.

6. Report:

   • Branch/current feature name and spec file path
   • Requirement count and clarification marker count
   • Whether project context was written
   • Next workflow step: /spec-kit:clarify only if material markers remain, otherwise /spec-kit:plan