speckl

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.

Context

• Refinement instructions: $ARGUMENTS
• Current spec: !cat spec/.current 2>/dev/null || echo "No active spec"
• Project context: @CLAUDE.md

Your Task

Phase 0: Context Check

1. Check for CLAUDE.md

   • If CLAUDE.md is not found in project root, display this warning once:

     ⚠️  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)
     
     Proceeding without project context may result in less focused specifications.
     

2. Check for README.md

   • If spec/<current-spec>/README.md is not found, display this warning:

     ⚠️  No README.md found in the spec directory. This file should contain the feature description
     to guide spec creation. Consider running `/spkl:init "feature description"` to set up properly.
     

Phase 1: Read Feature Description

1. Read the README.md in the current spec directory
   • Read spec/<current-spec>/README.md to understand the feature description
   • This is your primary source of truth for what the user wants to build

Phase 2: Research (REQUIRED)

Always research before proceeding:

1. Use the README.md description to understand the feature intent and context
2. Search for similar existing implementations in the codebase
3. Research relevant best practices, technical requirements, and security/performance considerations
4. Validate assumptions about external APIs, libraries, or standards

For refinements, focus on how $ARGUMENTS impacts the existing spec. Present findings before Phase 3.

Note: The README.md acts as your research brief. Use it to guide what areas of the codebase need investigation.

Phase 3: Spec Creation or Review

1. If spec/<current-spec>/spec.md does not exist, create it via Write with this minimal template (use README.md description and research findings to populate):

   # <short title>
   
   # Goal
   <user/system outcome>
   
   # Inputs
   - <specific data, params, triggers - include concrete values/enums if relevant>
   
   # Outputs
   - <UI state / API / file>
   
   # Constraints
   - <stack, performance, compliance>
   
   # Requirements
   - <WHAT needs to be built, not HOW - avoid code snippets, focus on components/capabilities>
   
   # Dependencies
   - <existing systems to study before implementing - read these to understand patterns and context>
   
   # Out of Scope
   - <explicit non-goals>
   
   # Done
   - <user-observable outcomes - behaviors the user can see/test, not technical tasks>
   

2. If spec/<current-spec>/spec.md exists:

   • Print the current spec content for reference.
   • If $ARGUMENTS is provided, apply the refinement instructions to improve the spec.
   • If $ARGUMENTS is empty, offer to review the spec for clarity and completeness.
   • Suggest improvements as a unified diff (GNU diff -u format) against the existing text.
   • Interpret $ARGUMENTS as guidance on what to clarify, tighten, or adjust (e.g., "make constraints more specific", "clarify the auth flow", "add performance requirements").
   • Do not expand scope unless explicitly requested—focus on ambiguity removal, tighter constraints, clearer Done items.

Critical Constraints

Evidence-Based Suggestions Only:

✅ INCLUDE if there's direct evidence:

• Systems that already display/process this exact data type (e.g., if transaction log shows refunds, mention it for refund reason feature)
• Areas that must change because they currently handle the feature being modified
• Components explicitly named in the user's outline or existing spec

❌ EXCLUDE if speculative:

• Systems that could theoretically use this data but don't currently (e.g., analytics that doesn't mention refunds)
• "Nice to have" integrations that aren't already connected
• Tangentially related features that might benefit

Evidence test: Before suggesting any system/area, confirm:

1. Does it currently handle this exact data/feature? OR
2. Did the user explicitly mention it in their outline?

If both answers are "no", don't include it.

Guidelines

• KISS. Boundaries over blueprints.
• Dependencies: List existing systems developers should read/understand before starting. Include components you'll modify if understanding them is prerequisite.
• Requirements: State WHAT needs building, not HOW. No code snippets. "Create RefundReason enum", not "public enum RefundReason { ... }"
• Done: Observable user outcomes only. "Merchants can select refund reason" not "RefundReason enum created"
• Prefer edits that remove ambiguity rather than add new scope.
• Ground specs in research, not assumptions.
• If uncertain about technical details, search first, spec second.
• When in doubt, leave it out. Smaller, focused specs ship faster.
• Better to under-specify than over-promise.
• When refining, address the specific concerns in $ARGUMENTS while maintaining the spec's structure.

After Completion

• For creation:
  • Confirm the spec was written to spec/<current-spec>/spec.md
  • Explain that the spec was created from the README.md description plus research findings
  • Suggest running /spkl:spec <refinements> if changes are needed
• For refinement: Ask if user wants to apply the suggested diff

Context

• Current spec: !cat spec/.current 2>/dev/null || echo "No active spec"
• Project context: @CLAUDE.md

Your Task

Phase 1: Validation

1. Verify that spec/<current-spec>/spec.md exists
2. If not found, inform the user to run /spkl:spec first

Phase 2: Task Breakdown

Translate the spec into concrete, implementable tasks for human developers (not AI execution instructions):

• From Requirements section: Create concrete implementation tasks
• From Dependencies section: Understand context, but don't create "read X" tasks
• From Constraints section: Use to inform task creation, but don't duplicate them as tasks
• From Done criteria: Use to validate task completeness

Structure:

• Organize tasks into logical categories (e.g., "Core Models", "API Layer", "UI Components")
• Number categories sequentially (1, 2, 3, etc.)
• Number tasks within each category using decimal notation (1.1, 1.2, 1.3, etc.)
• Use markdown checkbox notation for each task: - [ ] 1.1 Task description
• Keep granularity appropriate (not too high-level, not overly detailed)
• Focus on what needs to be done, not how to do it

Update behavior:

• If spec/<current-spec>/tasks.md exists, overwrite with fresh task list (developers manually check off completed tasks)

• Save tasks to spec/<current-spec>/tasks.md

Critical Constraints

• Do not include constraints, dependencies, or success criteria in the task list - those remain in the spec to guide implementation
• Test scenarios/validation may be included as tasks if helpful, but consolidate into broad validation areas rather than individual test cases

Consolidation strategy for validation tasks:

• Group by system area (e.g., "API versioning", "UI validation", "persistence")
• Group by user flow (e.g., "refund flows", "authentication flows")
• Typically aim for 3-5 validation tasks total, not 7+
• Example: Instead of separate tasks for "test full refund" and "test partial refund", use "Verify refund flows work correctly (full and partial)"

Guidelines

• Tasks describe what to build, not implementation steps
• Avoid creating meta-tasks like "Read file X" or "Understand Y" (Dependencies section already lists these)
• Each task should be independently understandable and completable
• Tasks should map clearly back to Requirements in the spec

Example format:

# <spec name>: Implementation Tasks

**1. Core Models**
- [ ] 1.1 Create RefundReason enum in transaction domain
- [ ] 1.2 Add refund_reason field to Refund model

**2. API Layer**
- [ ] 2.1 Update RefundRequest schema to include reason
- [ ] 2.2 Add validation for required reason field

**3. UI Components**
- [ ] 3.1 Add reason dropdown to refund form
- [ ] 3.2 Update refund confirmation to display selected reason

**4. Validation**
- [ ] 4.1 Verify refund flows work correctly (full and partial refunds)
- [ ] 4.2 Verify UI validation and display (dropdown, confirmation, history)
- [ ] 4.3 Verify refund reason persistence in transaction logs

After Completion

• Confirm tasks were written to spec/<current-spec>/tasks.md
• Summarize the number of categories and tasks created