shep: Skill for Claude Code

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

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