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

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

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:

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/ ← 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:

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

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, "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:

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

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.