name: framework description: Expert knowledge of SpecWeave framework structure, rules, conventions, and increment lifecycle. Deep understanding of source-of-truth discipline, increment naming, living docs sync. Covers SpecWeave-specific hooks (post-task-completion), and increment discipline. Activates for specweave rules, increment lifecycle, source of truth, increment naming, tasks.md format, spec.md structure, living docs sync, specweave hooks, where do files go, how to use specweave, specweave best practices, specweave conventions. allowed-tools: Read, Grep, Glob

SpecWeave Framework Expert

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:

Specification First - Write WHAT and WHY before HOW
Incremental Delivery - Ship small, complete features
Living Documentation - Docs update automatically via hooks
Source of Truth Discipline - Single source, zero duplication
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 (v0.31.0+)

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

Increment Naming Convention (v0.6.0+)

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 (v0.6.0+)

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:close to close incomplete work
--force flag for emergencies (logged, should be rare)

What "DONE" Means:

All tasks in tasks.md marked [x] Completed, OR
COMPLETION-SUMMARY.md exists with "✅ COMPLETE" status, OR
Explicit closure via /sw:close

Three Options for Closing:

Adjust Scope - Remove features from spec.md, regenerate tasks
Move Scope - Transfer incomplete tasks to next increment
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:close
# 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/              ← ONE source of truth for ALL repos
├── auth-service/            ← Separate git repo
├── payment-service/         ← Separate git repo
├── frontend/                ← Separate git repo
└── infrastructure/          ← Separate git repo

Source of Truth Discipline

CRITICAL PRINCIPLE: SpecWeave has strict source-of-truth rules!

Three Directories, Three Purposes

src/                         ← SOURCE OF TRUTH (version controlled)
├── skills/                  ← Source for skills
├── agents/                  ← Source for agents
├── commands/                ← Source for slash commands
├── hooks/                   ← Source for hooks
├── adapters/                ← Tool adapters (Claude/Cursor/Copilot/Generic)
└── templates/               ← Templates for user projects

.claude/                     ← INSTALLED (gitignored in user projects)
├── skills/                  ← Installed from src/skills/
├── agents/                  ← Installed from src/agents/
├── commands/                ← Installed from src/commands/
└── hooks/                   ← Installed from src/hooks/

.specweave/                  ← FRAMEWORK DATA (always present)
├── increments/              ← Feature development
├── docs/                    ← Strategic documentation
└── logs/                    ← Logs and execution history

Golden Rules

✅ ALWAYS edit files in src/ (source of truth)
✅ Run install scripts to sync changes to .claude/
❌ NEVER edit files in .claude/ directly (they get overwritten)
❌ NEVER create new files in project root (use increment folders)

Example Workflow:

# CORRECT: Edit source
vim src/skills/increment-planner/SKILL.md

# Sync to .claude/
npm run install:skills

# Test (skill activates from .claude/)
/sw:inc "test feature"

# WRONG: Edit installed file
vim .claude/skills/increment-planner/SKILL.md  # ❌ Gets overwritten!

File Organization Rules

✅ ALLOWED in Root:

CLAUDE.md (this file)
README.md, CHANGELOG.md, LICENSE
Standard config files (package.json, tsconfig.json, .gitignore)
Build artifacts (dist/, only if needed temporarily)

❌ NEVER Create in Root (pollutes repository): All AI-generated files MUST go into increment folders:

❌ WRONG:
/SESSION-SUMMARY-2025-10-28.md          # NO!
/ADR-006-DEEP-ANALYSIS.md               # NO!
/ANALYSIS-MULTI-TOOL-COMPARISON.md      # NO!

✅ CORRECT:
.specweave/increments/0002-core-enhancements/
├── reports/
│   ├── SESSION-SUMMARY-2025-10-28.md
│   ├── ADR-006-DEEP-ANALYSIS.md
│   └── ANALYSIS-MULTI-TOOL-COMPARISON.md
├── logs/
│   └── execution-2025-10-28.log
└── scripts/
    └── migration-helper.sh

Why?

✅ Complete traceability (which increment created which files)
✅ Easy cleanup (delete increment folder = delete all files)
✅ Clear context (all files for a feature in one place)
✅ No root clutter

Hook System

What are Hooks?

Hooks are shell scripts that fire automatically on SpecWeave events:

post-task-completion - After EVERY task completion via TodoWrite
pre-task-plugin-detect - Before task execution (plugin detection)
post-increment-plugin-detect - After increment creation
pre-implementation - Before implementation starts

Current Hook: post-task-completion

Fires: After EVERY TodoWrite call Purpose: Notify when work completes

What it does (v2.0):

✅ Detects session end (inactivity-based, 15s threshold)
✅ Plays notification sound (macOS/Linux/Windows)
✅ Shows completion message
✅ Logs to .specweave/logs/hooks-debug.log
✅ Debounces duplicate fires (2s window)

What it does NOT do yet (planned for v0.6.1):

⏳ Update tasks.md completion status
⏳ Sync living docs automatically
⏳ Consolidate GitHub/Jira tasks
⏳ Calculate increment progress percentage

Smart Session-End Detection:

Problem: Claude creates multiple todo lists → sound plays multiple times
Solution: Track inactivity gaps between TodoWrite calls
- Rapid completions (< 15s gap) = Claude still working → skip sound
- Long gap (> 15s) + all done = Session ending → play sound!

Hook Configuration

File: .specweave/config.json

{
  "hooks": {
    "post_task_completion": {
      "enabled": true,
      "update_tasks_md": false,       // TODO: v0.6.1
      "sync_living_docs": false,      // TODO: v0.6.1
      "play_sound": true,
      "show_message": true
    }
  }
}

Manual Actions (Until v0.6.1)

Until hooks are fully automated, YOU MUST:

Update CLAUDE.md when structure changes
Update README.md for user-facing changes
Update CHANGELOG.md for API changes
Update tasks.md completion status manually (or use TodoWrite carefully)

Plugin Architecture (v0.4.0+)

Core vs. Plugin

Core Framework (always loaded):

8 core skills (increment-planner, spec-generator, context-loader, etc.)
3 core agents (PM, Architect, Tech Lead)
7 core commands (/sw:inc, /sw:do, etc.)

Plugins (opt-in):

specweave-github - GitHub integration (issue sync, PR creation)
specweave-jira - Jira integration (task sync)
specweave-kubernetes - K8s deployment (planned)
specweave-frontend-stack - React/Vue/Angular (planned)
specweave-ml-ops - Machine learning (planned)

Context Reduction

Before plugins (v0.3.7):

Simple React app: 50K tokens (ALL 44 skills + 20 agents loaded)
Backend API: 50K tokens
ML pipeline: 50K tokens

After plugins (v0.4.0+):

Simple React app: Core + frontend-stack + github ≈ 16K tokens (68% reduction!)
Backend API: Core + nodejs-backend + github ≈ 15K tokens (70% reduction!)
ML pipeline: Core + ml-ops + github ≈ 18K tokens (64% reduction!)

Four-Phase Plugin Detection

Init-Time (during specweave init):
- Scans package.json, directories, env vars
- Suggests plugins: "Found React. Enable frontend-stack? (Y/n)"
First Increment (during /sw:inc):
- Analyzes increment description for keywords
- Suggests before creating spec: "This needs kubernetes plugin. Enable? (Y/n)"
Pre-Task (before task execution):
- Hook scans task description
- Non-blocking suggestion: "This task mentions K8s. Consider enabling plugin."
Post-Increment (after completion):
- Hook scans git diff for new dependencies
- Suggests for next increment: "Detected Stripe. Enable payment-processing plugin?"

Hybrid Plugin System (v0.4.1)

SpecWeave plugins support dual distribution:

NPM Package (SpecWeave CLI):
- npm install -g specweave
- specweave plugin install github
- Works with ALL tools (Claude, Cursor, Copilot, Generic)
Claude Code Marketplace (Native /plugin):
- /plugin marketplace add https://github.com/anton-abyzov/specweave
- /plugin install specweave-github
- Best UX for Claude Code users (use HTTPS URL for public repos!)

Plugin Manifests (both required):

plugin.json - Claude Code native format
manifest.json - SpecWeave custom format (richer metadata)

Multi-Tool Support

SpecWeave works with multiple AI coding assistants:

Claude Code (⭐⭐⭐⭐⭐ 100%)

Native .claude/ installation
Skills auto-activate
Hooks fire automatically
Slash commands work natively
Agents isolate context
BEST EXPERIENCE

Cursor 2.0 (⭐⭐⭐⭐ 85%)

AGENTS.md compilation
Team commands via dashboard
@context shortcuts
Shared agent context (8 parallel agents)
Manual hook triggers

GitHub Copilot (⭐⭐⭐ 60%)

.github/copilot/instructions.md compilation
Natural language instructions only
Manual workflows
No hooks or slash commands

Generic (⭐⭐ 40%)

SPECWEAVE-MANUAL.md for copy-paste
Manual workflows
No automation

Recommendation: Use Claude Code for SpecWeave. Other tools work, but you'll miss the magic.

Key Commands

Increment Lifecycle

/sw:inc "feature-name" - Plan new increment (PM-led process)
/sw:do - Execute next task (smart resume)
/sw:progress - Show progress, PM gate status, next action
/sw:validate 0001 - Validate spec, tests, quality
/sw:done 0001 - Close increment (PM validation)
/sw:next - Auto-close if ready, suggest next work

Increment Discipline

/sw:status - Show all increments and completion status
/sw:close - Interactive closure of incomplete increments

Documentation Sync

/sw:sync-docs review - Review strategic docs before implementation
/sw:sync-docs update - Update living docs from completed increments

External Platform Sync

/sw:sync-github - Bidirectional GitHub sync
/sw:sync-jira - Bidirectional Jira sync

Common Questions

Q: Where do I create a new increment?

A: Use /sw:inc "####-descriptive-name". It creates:

.specweave/increments/####-descriptive-name/
├── spec.md
├── plan.md
├── tasks.md
└── tests.md

Q: Where do I put analysis files?

A: In the increment's reports/ folder:

.specweave/increments/0002-core-enhancements/reports/
└── ANALYSIS-XYZ.md

Q: How do I know what tasks are left?

A: Use /sw:progress or read .specweave/increments/####/tasks.md

Q: Can I start a new increment before finishing the current one?

A: NO! (v0.6.0+) The framework blocks you. Use /sw:status to check, /sw:close to close.

Q: Where do I edit skills/agents/commands?

A: Edit in src/ (source of truth), then run npm run install:all to sync to .claude/

Q: How do I know if a plugin is needed?

A: SpecWeave auto-detects! It will suggest plugins during init or increment creation.

Q: Why does the hook play a sound?

A: Session-end detection! If all tasks complete AND you've been idle > 15s, it assumes you're done. Configurable in .specweave/config.json.

Q: How do I disable a hook?

A: Edit hooks/hooks.json and set "enabled": false for that hook.

Activation Keywords

I activate when you ask about:

SpecWeave rules / conventions / best practices
Increment naming / structure / lifecycle
Where files go / directory structure
Source of truth / what to edit
Hook system / automation
Plugin architecture / context reduction
How to use SpecWeave / getting started
What is spec.md / plan.md / tasks.md
Living docs sync
Increment discipline / closure
Multi-tool support (Claude/Cursor/Copilot)

When to Use Other Skills/Agents

increment-planner - Planning NEW increments (/sw:inc)
PM agent - Leading increment creation (auto-invoked by /sw:inc)
Architect agent - Designing system architecture
Tech Lead agent - Code review, best practices
spec-generator - Creating detailed technical RFCs
context-loader - Explaining context efficiency
diagrams-architect - Creating C4/Mermaid diagrams

I focus on framework knowledge. For increment execution, use the PM agent and commands!

Let me help you understand and use SpecWeave correctly! 🚀

framework

SpecWeave Framework Expert

Core Philosophy

Increment-Based Development

What is an Increment?

spec.md Mandatory Fields (v0.31.0+)

Increment Naming Convention (v0.6.0+)

Increment Lifecycle

Increment Discipline (v0.6.0+)

Directory Structure

Root-Level .specweave/ Folder (MANDATORY)

Source of Truth Discipline

Three Directories, Three Purposes

Golden Rules

File Organization Rules

Hook System

What are Hooks?

Current Hook: post-task-completion

Hook Configuration

Manual Actions (Until v0.6.1)

Plugin Architecture (v0.4.0+)

Core vs. Plugin

Context Reduction

Four-Phase Plugin Detection

Hybrid Plugin System (v0.4.1)

Multi-Tool Support

Claude Code (⭐⭐⭐⭐⭐ 100%)

Cursor 2.0 (⭐⭐⭐⭐ 85%)

GitHub Copilot (⭐⭐⭐ 60%)

Generic (⭐⭐ 40%)

Key Commands

Increment Lifecycle

Increment Discipline

Documentation Sync

External Platform Sync

Common Questions

Q: Where do I create a new increment?

Q: Where do I put analysis files?

Q: How do I know what tasks are left?

Q: Can I start a new increment before finishing the current one?

Q: Where do I edit skills/agents/commands?

Q: How do I know if a plugin is needed?

Q: Why does the hook play a sound?

Q: How do I disable a hook?

Activation Keywords

When to Use Other Skills/Agents

Related Skills