Spec

Skill bitcraft-apps/spec-first/skills/spec

Create specifications through parallel analysisFrom its SKILL.md

Install

npx -y skills add bitcraft-apps/spec-first --skill spec

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.8 KB, as published. Nobody here has run it

Spec Command

Creates a specification from requirements. One agent does the steps in order.

Usage

/sf:spec [REQUIREMENTS]

Context

Read the current branch, the last 5 commits, and the working tree. Check whether .sf/spec.md exists.

Clarification Check

If the requirements are vague (fewer than 15 words, or unclear), ask the user before you start. Wait for the answer. Do not assume. Ask about:

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

The working directory is .sf/. $SF_DIR overrides it.

Pick the mode:

No .sf/spec.md → first
.sf/spec.md exists → ask the user: "Update existing" / "Create new" → update / new

Run scripts/spec-dir.sh <first|update|new>, in this skill directory. If spec-dir.sh fails (non-zero exit), halt immediately — do not do the work below.

Execution

Write each file in turn. The requirements are the input to this skill.

.sf/research/scope.md — the narrowest viable change. Exclude what is not needed now.
.sf/research/criteria.md — the simplest testable pass/fail conditions.
.sf/research/risks.md — blockers only, not every possible risk.
$SF_DIR/spec.md — merge the three files. Keep it under 50 lines. Use the structure in spec-template.md, next to this file.

Gate — Post-Spec: run scripts/validate-spec.sh, in this skill directory. If it fails (non-zero exit), add the sections it names, then run it again. Do not report done.

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

Say: "Spec written to {output path}. Run /sf:implement to build it."

On Claude Code

Claude Code runs steps 1 to 3 as the sf-spec workflow — in parallel, schema-checked, and without the research files.

Context arrives for free:

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
Existing spec: !test -f .sf/spec.md && echo "yes" || echo "no"
Use the AskUserQuestion tool for both questions above, so execution pauses for the answer.
Bash: bash ${CLAUDE_PLUGIN_ROOT}/scripts/spec-dir.sh $MODE ${CLAUDE_PROJECT_DIR:+$CLAUDE_PROJECT_DIR/.sf}
Workflow tool, name: "sf-spec". Pass args as a JSON object, never as a string: {"requirements": "$ARGUMENTS", "specPath": "<the spec.md path above>", "templatePath": "${CLAUDE_SKILL_DIR}/spec-template.md"}
Gate: bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate-spec.sh ${CLAUDE_PROJECT_DIR:+$CLAUDE_PROJECT_DIR/.sf}