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

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

yaml

# 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

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

code

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:

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

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:

bash

# 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:

code

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):

code

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:

code

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

code

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:

bash

# 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:

code

❌ 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:

•✅ 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:

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

Smart Session-End Detection:

code

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

json

{
  "hooks": {
    "post_task_completion": {
      "enabled": true,
      "update_tasks_md": false,
      "sync_living_docs": false,
      "play_sound": true,
      "show_message": true
    }
  }
}

Manual Actions

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

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:

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

After plugins:

•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

SpecWeave plugins support dual distribution:

•
NPM Package (SpecWeave CLI):
- •npm install -g specweave
- •specweave plugin install sw-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 sw-github@specweave
- •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-github:sync - Bidirectional GitHub sync
•/sw-jira:sync - Bidirectional Jira sync

Common Questions

Q: Where do I create a new increment?

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

code

.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:

code

.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! 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! 🚀

Project-Specific Learnings

Before starting work, check for project-specific learnings:

bash

# Check if skill memory exists for this skill
cat .specweave/skill-memories/framework.md 2>/dev/null || echo "No project learnings yet"

Project learnings are automatically captured by the reflection system when corrections or patterns are identified during development. These learnings help you understand project-specific conventions and past decisions.