--- name: framework description: Expert on SpecWeave framework structure, rules, and spec-driven development conventions. Use when learning SpecWeave best practices, understanding increment lifecycle, or configuring hooks. Covers source-of-truth discipline, tasks.md/spec.md formats, living docs sync, and file organization patterns. allowed-tools: Read, Grep, Glob user-invocable: false --- # 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**: 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): ```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](/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:close` 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:close` **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**: ```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: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 1. **✅ ALWAYS edit files in `src/`** (source of truth) 2. **✅ Run install scripts to sync changes to `.claude/`** 3. **❌ NEVER edit files in `.claude/` directly** (they get overwritten) 4. **❌ 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: ``` ❌ 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` ```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 1. **Init-Time** (during `specweave init`): - Scans package.json, directories, env vars - Suggests plugins: "Found React. Enable frontend-stack? (Y/n)" 2. **First Increment** (during `/sw:inc`): - Analyzes increment description for keywords - Suggests before creating spec: "This needs kubernetes plugin. Enable? (Y/n)" 3. **Pre-Task** (before task execution): - Hook scans task description - Non-blocking suggestion: "This task mentions K8s. Consider enabling plugin." 4. **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**: 1. **NPM Package** (SpecWeave CLI): - `npm install -g specweave` - `specweave plugin install sw-github` - Works with ALL tools (Claude, Cursor, Copilot, Generic) 2. **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: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! 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.