spec

Spec Command

Creates specifications with intelligent clarification.

Usage

/sf:spec [REQUIREMENTS]

---

Project Context

• Branch: !git branch --show-current 2>/dev/null
• Recent commits: !git log --oneline -5 2>/dev/null
• Working tree: !git status --short 2>/dev/null | head -20

Clarification Check

If requirements are vague (< 15 words or unclear), use the AskUserQuestion tool to gather missing context. Do NOT output questions as plain text — always use the tool so execution pauses for the user's answer.

Questions to consider asking:

• What specific problem are you solving?
• Who are the users?
• What's the desired outcome?
• Any technical constraints?
• What's the minimal viable version?

Directory Management

Claude Code will use .claude/.sf/ as the working directory.

Command-level logic:

If .claude/.sf/spec.md exists:
    Use AskUserQuestion tool: "Existing spec found. What would you like to do?"
      Options: "Update existing" / "Create new"
    If user chooses update: Write "update" to .claude/.sf/mode
    If user chooses new: Write "new" to .claude/.sf/mode
Else:
    Write "first" to .claude/.sf/mode

Execution

After directory setup and clarification (if needed), run agents:

Pre-execution:

• Task: manage-spec-directory (maxTurns: 3) (reads mode from $SF_DIR/mode file)
• If manage-spec-directory fails (non-zero exit), halt immediately — do not run downstream agents.

Batch 1 (Parallel):

• Task: define-scope (maxTurns: 6) with requirements: $ARGUMENTS
• Task: create-criteria (maxTurns: 6) with requirements: $ARGUMENTS
• Task: identify-risks (maxTurns: 6) with requirements: $ARGUMENTS

Batch 2:

• Task: synthesize-spec (maxTurns: 12) to combine all research, following the structure in ${CLAUDE_SKILL_DIR}/spec-template.md

Output: $SF_DIR/spec.md (direct file or symlink to timestamped spec)

Error Recovery

If any agent fails:

1. Claude Code shows the specific error
2. Fix the issue (usually unclear requirements)
3. Re-run /sf:spec with clearer input
4. No partial state - each run starts fresh