/framework

description: SpecWeave framework expert for structure, rules, spec-driven conventions. Use for SpecWeave best practices, increment lifecycle, hooks, tasks.md/spec.md, living docs sync.
allowed-tools: Read, Grep, Glob
user-invocable: false

SpecWeave Framework Expert

Project Overrides

**Skill Memories**: If `.specweave/skill-memories/framework.md` exists, read and apply its learnings.

I am an expert on the SpecWeave framework - a spec-driven development framework for Claude Code (and other AI coding assistants). I have deep knowledge of its structure, rules, conventions, and best practices.

Core Philosophy

SpecWeave follows **spec-driven development** with **increment-based workflows**:

1. **Specification First** - Write WHAT and WHY before HOW 2. **Incremental Delivery** - Ship small, complete features 3. **Living Documentation** - Docs update automatically via hooks 4. **Source of Truth Discipline** - Single source, zero duplication 5. **Multi-Tool Support** - Works with Claude, Cursor, Copilot, and generic AI

Increment-Based Development

What is an Increment?

An **increment** = a complete feature with:

• `spec.md` - Product requirements (WHAT and WHY) — **required**
• `plan.md` - Technical architecture (HOW to implement) — **optional**, for complex features only
• `tasks.md` - Task breakdown (WORK to do) — **required**
• `metadata.json` - State tracking — **required**

> **When to skip plan.md**: Bug fixes, simple migrations, hotfixes, and straightforward tasks where spec.md already describes the approach.

spec.md Mandatory Fields

**CRITICAL**: spec.md YAML frontmatter MUST include project (and board for 2-level structures):

# 1-level structure (single-project or multiProject):
---
increment: 0001-feature-name
project: my-project          # REQUIRED
---

# 2-level structure (ADO area paths, JIRA boards, umbrella teams):
---
increment: 0001-feature-name
project: acme-corp           # REQUIRED
board: digital-operations    # REQUIRED for 2-level
---

**Why?** Ensures increment syncs to correct location in living docs. Without explicit project/board, sync-specs may fail or place specs in wrong folder.

**Detection**: Use `src/utils/structure-level-detector.ts` to determine if 1-level or 2-level structure is needed.

**See**: [ADR-0190](/internal/architecture/adr/0190-spec-project-board-requirement.md)

Increment Naming Convention

**CRITICAL RULE**: All increments MUST use descriptive names, not just numbers!

**Format**: `####-descriptive-kebab-case-name`

**Examples**:

• ✅ `0001-core-framework`
• ✅ `0002-core-enhancements`
• ✅ `0003-intelligent-model-selection`
• ✅ `0004-plugin-architecture`
• ✅ `0006-llm-native-i18n`
• ❌ `0003` (too generic, rejected!)
• ❌ `0004` (no description, rejected!)

**Rationale**:

• Clear intent at a glance
• Easy to reference in conversation
• Better git history
• Searchable by feature name
• Self-documenting increment folders

Increment Lifecycle

1. Plan    → sw:inc "feature-name"
            ↓ PM agent creates spec.md, plan.md, tasks.md, tests.md

2. Execute → sw:do
            ↓ Selects next task, executes, marks complete

3. Validate → sw:validate 0001
            ↓ Checks spec compliance, test coverage

4. Close   → sw:done 0001
            ↓ Creates COMPLETION-SUMMARY.md, archives

Increment Discipline

**THE IRON RULE**: Cannot start increment N+1 until increment N is DONE!

**Enforcement**:

• `sw:inc` **blocks** if previous increments incomplete
• Use `sw:status` to check all increments
• Use `sw:done` to close incomplete work
• `--force` flag for emergencies (logged, should be rare)

**What "DONE" Means**: 1. All tasks in `tasks.md` marked `[x] Completed`, OR 2. `COMPLETION-SUMMARY.md` exists with "✅ COMPLETE" status, OR 3. Explicit closure via `sw:done`

**Three Options for Closing**: 1. **Adjust Scope** - Remove features from spec.md, regenerate tasks 2. **Move Scope** - Transfer incomplete tasks to next increment 3. **Extend Existing** - Update spec.md, add tasks, continue in same increment

**Example**:

# Check status
sw:status
# Shows: 0002 (73% complete), 0003 (50% complete)

# Try to start new increment
sw:inc "0004-new-feature"
# ❌ Blocked! "Close 0002 and 0003 first"

# Close previous work
sw:done
# Interactive: Choose force-complete, move tasks, or reduce scope

# Now can proceed
sw:inc "0004-new-feature"
# ✅ Works! Clean slate

Directory Structure

Root-Level .specweave/ Folder (MANDATORY)

**CRITICAL ARCHITECTURE RULE**: SpecWeave ONLY supports root-level `.specweave/` folders.

**Correct Structure**:

my-project/
├── .specweave/              ← ONE source of truth (root-level)
│   ├── increments/
│   │   ├── 0001-core-framework/
│   │   │   ├── spec.md
│   │   │   ├── plan.md
│   │   │   ├── tasks.md
│   │   │   ├── tests.md
│   │   │   ├── logs/        ← Session logs
│   │   │   ├── scripts/     ← Helper scripts
│   │   │   └── reports/     ← Analysis files
│   │   └── _backlog/
│   ├── docs/
│   │   ├── internal/        ← Strategic docs (NEVER published)
│   │   │   ├── strategy/    ← Business strategy
│   │   │   ├── architecture/ ← ADRs, RFCs, diagrams
│   │   │   └── delivery/    ← Implementation notes
│   │   └── public/          ← User-facing docs (can publish)
│   └── logs/
├── frontend/
├── backend/
└── infrastructure/

**WRONG** (nested .specweave/ folders - NOT SUPPORTED):

my-project/
├── .specweave/              ← Root level
├── backend/
│   └── .specweave/          ← ❌ NESTED - PREVENTS THIS!
└── frontend/
    └── .specweave/          ← ❌ NESTED - PREVENTS THIS!

**Why Root-Level Only?**

• ✅ Single source of truth
• ✅ Cross-cutting features natural (frontend + backend + infra)
• ✅ No duplication or fragmentation
• ✅ Clear ownership
• ✅ Simplified living docs sync

**Multi-Repo Solution**: For huge projects with multiple repos, create a **parent folder**:

my-big-project/              ← Create parent folder
├── .specweave