Speck Workflow Skill

Purpose: Automatically interpret Speck specification artifacts (spec.md, plan.md, tasks.md) and answer natural language questions about features without requiring explicit slash commands.

Activation: This skill activates when users ask questions about Speck features, mention file types (spec/plan/tasks), or reference Speck concepts (requirements, user stories, architecture, etc.).

Scope: Read-only operations. This skill NEVER modifies files. For creating or updating files, guide users to appropriate slash commands.

Additional Resources:

reference.md - Detailed interpretation rules, file states, error formats
examples.md - Usage examples showing skill in action
workflows.md - Advanced features (multi-repo, worktrees, session handoff)

Core Capabilities

1. Feature Discovery

When users reference features, use three-tier matching to locate the correct feature directory:

Tier 1: Exact Match (Highest Priority)

Direct directory name match: specs/005-speck-skill/

Tier 2: Numeric Prefix Match (High Priority)

User provides feature number (e.g., "005", "5", "feature 003")
Zero-pad numbers to 3 digits: "5" → "005"
Match against pattern: specs/NNN-*/

Tier 3: Fuzzy/Substring Match (Lower Priority)

User provides partial name (e.g., "skill", "auth", "plugin")
Filter by case-insensitive substring match
If multiple matches, ask for clarification

Disambiguation: When multiple features match, check conversation context first. If ambiguous, ask: "Did you mean: 003-user-auth or 012-auth-tokens?"

Error Handling: List all available features, use Levenshtein distance for typo suggestions, explain matching rules.

Worktree Context: Worktrees share the same specs/ directory as main repository. Feature discovery works identically in worktrees and main repo.

2. Template References

Speck uses templates in $PLUGIN_ROOT/templates/ to define expected structure for artifacts:

Template Locations:

Spec template: $PLUGIN_ROOT/templates/spec-template.md
Plan template: $PLUGIN_ROOT/templates/plan-template.md
Tasks template: $PLUGIN_ROOT/templates/tasks-template.md

When to Reference Templates:

User asks "What should go in [section]?" → Extract HTML comments from template
User asks "Does my [spec/plan/tasks] follow the template?" → Compare against template (see reference.md for workflow)

Template Structure: Templates use consistent markdown patterns (H1/H2/H3) with HTML comments for section purposes and guidelines.

3. Section Annotation Patterns

Summary: Templates use inline annotations to indicate section requirements.

Mandatory sections: ## Section Name *(mandatory)*
Conditional sections: ## Section Name *(include if...)*
HTML comments: Provide guidance (ACTION REQUIRED, IMPORTANT, general purpose)

For full details: See reference.md

4. File State Classification

Every artifact file can be in one of five states:

MISSING - File doesn't exist → ERROR
EMPTY - File exists but has no content → ERROR
MALFORMED - Invalid markdown/structure → WARNING (extract partial info)
INCOMPLETE - Missing mandatory sections → WARNING (calculate completeness %)
VALID - All mandatory sections present → SUCCESS

Graceful Degradation: For MALFORMED and INCOMPLETE states, extract maximum possible information, return completeness score, list warnings, provide recovery guidance.

For full details: See reference.md

5. Error Message Format

Summary: Use structured format with severity, context, and recovery guidance.

Example:

ERROR: Spec Not Found
┌──────────────────────────────────────────────────┐
│ spec.md not found at specs/006-feature/          │
├──────────────────────────────────────────────────┤
│ Recovery: Run /speck.specify "Feature desc"      │
└──────────────────────────────────────────────────┘

Severity Levels: ERROR (blocking), WARNING (non-blocking), INFO (informational)

For full details and examples: See reference.md

6. Conversation Context Tracking

Track:

Recently mentioned features (last 5)
Current feature context
Implicit references ("it", "that", "the spec")

Usage: Resolve implicit references to features discussed earlier in conversation. Reset context when user explicitly mentions different feature or after 10+ turns.

7. Multi-Repo Mode Detection

Summary: Detect if project uses multi-repo mode via .speck/root symlink.

Key Concepts:

Detection: Check for .speck/root symlink → multi-repo child repo
Child repos: Share specs/ directory, have local plan.md/tasks.md
Root repo: Contains shared specs/, manages constitution

Query Examples:

"Is this a multi-repo setup?" → Check for symlink
"What's the parent spec?" → Read metadata from spec.md

For full details: See workflows.md

8. Worktree Mode Detection

Summary: Detect Git worktree integration for isolated parallel development.

Key Concepts:

Detection: Check .speck/config.json for worktree.enabled: true
Metadata: .speck/worktrees/<branch>.json tracks worktree associations
File rules: Configuration files copied, dependencies symlinked
IDE auto-launch: VSCode/Cursor/JetBrains launch automatically

Query Examples:

"Is this in a worktree?" → Check metadata or git worktree list
"What's the worktree config?" → Read config.json

For full details: See workflows.md

9. Session Handoff

Summary: Automatic context transfer when creating new feature worktrees.

Key Concepts:

Handoff document: .speck/handoff.md written to new worktrees
SessionStart hook: Automatically loads handoff context when Claude session starts
Self-cleanup: Hook archives handoff after loading and removes itself from settings
Context transfer: Feature context, spec location, and pending tasks transferred to new session

How It Works:

When /speck.specify creates a new worktree, it writes .speck/handoff.md
It also configures .claude/settings.json with a SessionStart hook
When a new Claude session starts in the worktree, the hook fires
The hook reads handoff.md and injects context via hookSpecificOutput.additionalContext
After loading, the hook archives the handoff file and removes itself

Query Examples:

"What's in the handoff document?" → Read .speck/handoff.md in worktree
"Did the session handoff work?" → Check for .speck/handoff.done.md (archived)
"How do I create a feature with handoff?" → Use /speck.specify "Feature description"

Handoff Document Contents:

Feature name and spec location
Repository context (single/multi-repo mode)
Pending implementation tasks
Relevant file paths and references

Artifact Interpretation Quick Reference

For detailed artifact interpretation (metadata blocks, mandatory sections, parsing rules), see reference.md.

spec.md: Requirements, user stories, success criteria plan.md: Implementation approach, technical context, constitution check tasks.md: Task breakdown, dependencies, checkpoints

Limitations

Read-Only Operations: This skill NEVER modifies files. For creating or updating Speck artifacts:

Creating specs: /speck.specify "Feature description"
Clarifying specs: /speck.clarify
Generating plans: /speck.plan
Generating tasks: /speck.tasks
Creating checklists: /speck.checklist
Analyzing consistency: /speck.analyze

Non-Destructive Constraint:

Only reads existing files
Never writes, modifies, or deletes files
Never runs external commands or tools
Provides guidance to appropriate slash commands when modifications needed

Activation Limitations: Skill may not activate if query is too vague, about non-Speck topics, or doesn't establish feature context.

Troubleshooting Activation Issues

Issue: Too Vague ❌ "What's left?" ✅ "What tasks are left for feature 005?"

Issue: No Speck Context ❌ "Show me the plan" ✅ "Show me plan.md for the speck skill"

Issue: Wrong Topic ❌ "How do I implement this in TypeScript?" ✅ "What's the technical approach in the plan for feature 005?"

Best Practices:

Mention feature explicitly (number or name)
Use Speck terminology (spec, plan, tasks, requirements)
Be specific about file types
Establish context first

Slash Command Reference

This skill is for reading and understanding existing Speck artifacts. When users need to create or modify files, guide them to these slash commands:

| Command | Purpose | Example Trigger Phrase | | ------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------- | | /speck.specify | Create or update feature specification (with optional worktree creation) | "Run /speck.specify to create a new spec" | | /speck.clarify | Resolve ambiguities and add missing sections | "Run /speck.clarify to resolve [NEEDS CLARIFICATION] markers" | | /speck.plan | Generate implementation plan from spec | "Run /speck.plan to create the implementation plan" | | /speck.tasks | Generate actionable task breakdown | "Run /speck.tasks to create a task list" | | /speck.analyze | Check cross-artifact consistency and quality | "Run /speck.analyze to validate spec/plan/tasks consistency" | | /speck.implement | Execute tasks from tasks.md | "Run /speck.implement to start implementation" | | /speck.link | Link child repository to multi-repo root | "Run /speck.link ../root to connect this repo to multi-repo root" | | /speck.init | Install Speck CLI globally via symlink | "Run /speck.init to install the speck command" | | /speck.help | Load speck-help skill for natural language questions | "Run /speck.help to ask questions about Speck" | | /speck.env | Check Speck environment and configuration | "Run /speck.env to see current repo mode (single/multi-repo)" |

Worktree Flags for /speck.specify:

--no-worktree: Skip worktree creation
--no-ide: Skip IDE auto-launch
--no-deps: Skip dependency installation
--reuse-worktree: Reuse existing worktree if present

When to Suggest Commands:

Missing spec.md → Suggest /speck.specify "Feature description"
[NEEDS CLARIFICATION] markers → Suggest /speck.clarify
Missing plan.md → Suggest /speck.plan
Missing tasks.md → Suggest /speck.tasks
Incomplete sections → Suggest /speck.clarify or manual editing
After clarification → Suggest /speck.analyze to check consistency
After task generation → Suggest /speck.implement to execute tasks

For complete command list: Direct users to type /help in Claude Code.

Plugin Extensibility

Speck follows a modular architecture where specialized capabilities are delivered as optional plugins. This keeps the core Speck plugin focused on specification workflows while enabling extensions for related tasks.

Available Plugins

| Plugin | Command | Purpose | | ------------------ | ---------- | ------------------------------------------------------------------- | | speck | /speck.* | Core specification workflow (specify, plan, tasks, implement) | | speck-reviewer | /review | AI-assisted PR review with cluster analysis and Speck-aware context |

Installing Extension Plugins

All Speck plugins are installed through the Claude Code plugin system:

# Install speck-reviewer for PR reviews
/plugin install speck-reviewer@speck-market

speck-reviewer Plugin

The speck-reviewer plugin adds structured PR review capabilities:

Cluster-Based Review: Groups related files for coherent review sessions
Speck-Aware Context: References spec requirements when available
Comment Management: Stage, refine, and batch-post review comments
Session Persistence: Resume interrupted reviews

When to use: Use /speck-reviewer:review after creating a PR for a Speck feature. The plugin will automatically load any spec context for your branch.

Learn more: See plugin documentation for full usage guide.

Summary

This skill enables natural language interaction with Speck workflow artifacts:

✅ Automatically activates when users ask about features
✅ Interprets spec.md (requirements, user stories, success criteria)
✅ Interprets plan.md (technical approach, architecture, constitution)
✅ Interprets tasks.md (status, dependencies, progress)
✅ Compares files against templates
✅ Handles incomplete/malformed files gracefully
✅ Provides actionable recovery guidance
✅ Maintains conversation context for follow-up questions
✅ Read-only operations (non-destructive)

Additional Resources:

reference.md - Detailed rules, workflows, edge cases
examples.md - Usage examples
workflows.md - Advanced features (multi-repo, worktrees, session handoff)

Goal: Reduce need for manual file reading and slash command usage by 80%, enabling developers to ask natural questions and get accurate answers about their Speck features.