---
name: Shep New Feature
slug: shep-new-feature
category: Automation
description: Shep New Feature creates a spec branch and scaffolds a new feature specification directory. Use it when starting a new feature, functionality, or enhancement in the Shep spec-driven workflow.
github: "https://github.com/shep-ai/shep/tree/main/.claude/skills/shep-kit-new-feature"
language: TypeScript
stars: 247
forks: 53
install: "npx degit https://github.com/shep-ai/shep/tree/main/.claude/skills/shep-kit-new-feature ~/.claude/skills/shep-kit-new-feature"
installs_to: ~/.claude/skills/shep-kit-new-feature
source_path: .claude/skills/shep-kit-new-feature/SKILL.md
collection_size: 19
category_size: 1648
collection_url: "https://dirskills.com/collections/shep-ai/shep"
added: 2026-09-02T05:21:38.945Z
last_synced: 2026-09-02T05:21:38.945Z
canonical_url: "https://dirskills.com/skills/shep-new-feature"
---

# Shep New Feature

Shep New Feature creates a spec branch and scaffolds a new feature specification directory. Use it when starting a new feature, functionality, or enhancement in the Shep spec-driven workflow.

**Install:**

```bash
npx degit https://github.com/shep-ai/shep/tree/main/.claude/skills/shep-kit-new-feature ~/.claude/skills/shep-kit-new-feature
```

## README

# Create New Feature Specification


Start spec-driven development by creating a feature branch and specification directory.

**Full workflow guide:** [docs/development/spec-driven-workflow.md](../../../docs/development/spec-driven-workflow.md)

## Phase Lifecycle

```
Requirements → Research → Planning → Implementation → Complete
    ↓             ↓           ↓            ↓            ↓
 spec.yaml   research.yaml plan.yaml   tasks.yaml   all files
    ↓             ↓           ↓            ↓            ↓
 spec.md     research.md   plan.md     tasks.md     (auto-generated)
```

**CRITICAL:** Each phase MUST update the `Phase` status field before proceeding.

**IMPORTANT:** Edit YAML files, not Markdown.

## Workflow

### 1. Gather Minimal Input

Ask the user for:

- **Feature name** (kebab-case, e.g., `user-authentication`)
- **One-liner description** (brief summary)

### 2. Create Branch

```bash
# Determine next number
NEXT_NUM=$(ls -d specs/[0-9][0-9][0-9]-* 2>/dev/null | wc -l | xargs printf "%03d" $(($ + 1)))
# If no specs exist, use 001
[ -z "$NEXT_NUM" ] && NEXT_NUM="001"

# Create branch from main
git checkout main && git pull
git checkout -b "feat/${NEXT_NUM}-${FEATURE_NAME}"
```

### 3. Run Init Script

Execute the scaffolding script:

```bash
.claude/skills/shep-kit-new-feature/scripts/init-feature.sh <NNN> <feature-name>
```

This creates `specs/NNN-feature-name/` with all template files using a **YAML-first** approach:

- **YAML source files**: `spec.yaml`, `research.yaml`, `plan.yaml`, `tasks.yaml` (source of truth)
- **Markdown files**: `spec.md`, `research.md`, `plan.md`, `tasks.md` (auto-generated from YAML)
- **Status tracking**: `feature.yaml` (implementation status, unchanged)

### 4. Analyze Context

Before filling the spec, analyze:

- **Existing specs**: Read `specs/*/spec.yaml` (or `specs/*/spec.md`) to understand feature landscape and discover dependencies
- **Codebase**: Identify affected areas, patterns, existing implementations
- **Cross-reference**: Infer dependencies, impact areas, size estimate

### 5. Propose Spec Content

Fill the template placeholders with inferred values:

- Problem statement (from user description + context)
- Success criteria (inferred from scope)
- Affected areas with impact levels (from codebase analysis)
- Dependencies on other features (from existing specs)
- Size estimate with reasoning (S/M/L/XL)
- Open questions (gaps identified during analysis)

Present the proposed spec to the user for review.

### 6. User Confirms/Adjusts

Allow the user to:

- Approve the proposed spec
- Modify any inferred values
- Add missing context or requirements

### 7. Write Spec & Update feature.yaml

```bash
# Write confirmed content to spec.yaml (the source of truth)

# feature.yaml already created by init script with initial state:
#   - lifecycle: "research"
#   - phase: "research"
#   - checkpoint: "feature-created"
# See: docs/development/feature-yaml-protocol.md for details

# Stage and commit (both YAML source and generated Markdown)
git add specs/NNN-feature-name/
git commit -m "feat(specs): add NNN-feature-name specification"
```

**IMPORTANT:** Always edit `spec.yaml`. Never hand-edit Markdown spec files.

**feature.yaml Status**: Already initialized by init script. No manual updates needed at this stage.

### 8. Next Steps

Inform the user:

> Spec created on `feat/NNN-feature-name`!
> Next: `/shep-kit:research` to analyze technical approach.

## Open Questions Policy

**CRITICAL:** Open questions in `spec.yaml` (the `openQuestions` array) MUST be resolved before `/shep-kit:research`.

- If questions are identified, add them to the `openQuestions` array in `spec.yaml`
- User must confirm answers or mark the array empty (`openQuestions: []`)
- Research phase will REFUSE to proceed if unresolved open questions exist in `spec.yaml`

## Key Principles

- **Branch first**: All spec work happens on the feature branch
- **Infer, don't interrogate**: Analyze codebase to propose smart defaults
- **Dependencies from specs**: Scan existing `specs/*/spec.yaml` for relationships
- **User confirms**: Always get approval before writing files
- **Open questions block progress**: Never proceed with unresolved questions

## Template Location

Templates are in: `.claude/skills/shep-kit-new-feature/templates/`

### YAML Templates (Source of Truth)

- `spec.yaml` - Feature specification
- `research.yaml` - Technical decisions
- `plan.yaml` - Implementation strategy
- `tasks.yaml` - Task breakdown

### Other Templates

- `data-model.md` - Domain models
- `feature.yaml` - Status tracking

## feature.yaml Protocol

All shep-kit skills update `feature.yaml` as work progresses.

**Reference:** [docs/development/feature-yaml-protocol.md](../../../docs/development/feature-yaml-protocol.md)

**This skill's responsibility:**

- Create initial `feature.yaml` with:
  - `lifecycle: "research"`
  - `phase: "research"`
  - Checkpoint: "feature-created"

## Example

See: `.claude/skills/shep-kit-new-feature/examples/001-sample-feature/`