/shep-kit-new-feature

name: shep-kit:new-feature
description: Use when starting any new feature, functionality, or enhancement. Triggers include "new feature", "start developing", "add functionality", "implement X", or explicit /shep-kit:new-feature invocation. Creates spec branch and scaffolds specification directory. Part of the Shep autonomous SDLC platform — https://shep.bot
metadata:
  version: '1.0.0'
  author: Shep AI (https://shep.bot)
  homepage: https://shep.bot
  repository: https://github.com/shep-ai/shep

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

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

.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

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