sw-framework_skill

Overview

This skill is an expert guide to the SpecWeave framework structure, rules, and spec-driven development conventions. It helps teams adopt increment-based workflows, enforce source-of-truth discipline, and configure hooks and plugins. Use it to learn best practices for spec.md/tasks.md formats, living docs sync, and file organization patterns.

How this skill works

The skill inspects increment folders under a single root-level .specweave/ directory and validates required files (spec.md, tasks.md, metadata.json). It enforces naming and lifecycle rules, suggests when to include plan.md, and verifies project/board frontmatter for proper living-docs placement. It also explains hook behavior and plugin detection phases to help configure automation and manual update responsibilities.

When to use it

• When you need to create or review a new increment and ensure spec.md frontmatter is correct
• When implementing the SpecWeave root-level repository layout and source-of-truth rules
• When configuring or troubleshooting hooks (post-task-completion, pre-implementation, etc.)
• When deciding whether a feature needs plan.md or can skip it (bugs, hotfixes)
• When evaluating plugin suggestions and reducing context with a plugin set

Best practices

• Keep a single .specweave/ at repository root to maintain one source of truth
• Always edit source files in src/ and run install scripts to sync .claude/ artifacts
• Name increments with descriptive kebab-case: ####-descriptive-kebab-case-name
• Mark an increment DONE before starting the next; use /sw:status and /sw:close for enforcement
• Place all AI-generated outputs inside the corresponding increment folder, never in repo root

Example use cases

• Planning a small feature: create spec.md and tasks.md, skip plan.md for simplicity
• Onboarding a new repo: enforce .specweave/ layout, populate CLAUDE.md and README.md
• Hook tuning: enable post_task_completion sound and logs while leaving automatic task updates off
• Plugin enablement: run plugin detection during init and first increment to reduce context size
• Increment recovery: use /sw:close to move incomplete tasks to the next increment or shrink scope