gh-mattbrailsford-speckl/commands/spkl/init.md

allowed-tools, description, argument-hint

allowed-tools	description	argument-hint
Bash(mkdir:*), Bash(echo:*), Bash(test:*), Bash(ls:*), Write	Initialize a new specification	<feature-description>

Current Spec Status

!ls -d spec/[0-9][0-9][0-9]-* 2>/dev/null | wc -l | xargs -I {} echo "Total specs: {}"

Your Task

Initialize a new specification directory for feature: $ARGUMENTS

Steps:

1. Check for CLAUDE.md

   • Test if CLAUDE.md exists in project root
   • If missing, display warning:

     ⚠️  No CLAUDE.md found. SPECKL works best when your project has a CLAUDE.md file with:
        - Project overview and tech stack
        - Explicit non-goals (what you're NOT building)
        - Key constraints (performance, compliance, tech limits)
        - Design values (guiding principles)
     
     This helps `/spkl:spec` create better, more contextual specifications.
     

2. Extract and validate short name

   • Analyze the feature description in $ARGUMENTS
   • Extract a concise, descriptive folder name (2-4 words max)
   • Convert to kebab-case (lowercase, hyphens between words)
   • Use only alphanumeric characters and hyphens
   • Confirm the extracted name captures the essence of the feature

3. Create spec/ directory if it doesn't exist

4. Determine next sequential ID

   • Parse existing spec/[0-9][0-9][0-9]-* directories
   • Calculate next number (001, 002, ..., 010, 011, etc.)

5. Create specification directory

   • Format: spec/[ID]-<extracted-name>/
   • Verify creation succeeded

6. Create README.md with description

   • Write spec/[ID]-<extracted-name>/README.md
   • Format the original user description as markdown
   • Use clear heading structure:

     # <feature title>
     
     ## Description
     
     [Original user description]
     

7. Update tracking file

   • Write [ID]-<extracted-name> to spec/.current
   • This becomes the active spec for /spkl:spec and /spkl:tasks

8. Provide clear feedback

   • Show extracted folder name
   • Show created directory path
   • Confirm README.md contains the full description
   • Explain next step: run /spkl:spec to create spec.md

Use Bash and Write tools as needed. Handle errors gracefully.