SpecWeaver - Claude Code Plugin for AI-Powered Development

Professional Claude Code plugin for spec-driven feature development with multi-agent collaboration, automated code review, and intelligent workflow automation

Transform your software development with AI-powered development agents that automate architecture design, code quality analysis, and feature implementation. This comprehensive Claude AI plugin delivers systematic software development automation through 5 specialized agents and 3 powerful commands - perfect for developers using Claude Code who want to implement best practices, catch bugs early, and maintain high code quality throughout the entire development lifecycle.

Quick Start • Commands • Agents • Examples • Docs

---

🤔 The Problem with Traditional Software Development

Ever spent hours building a feature only to realize:

• ❌ You missed critical edge cases
• ❌ The architecture doesn't match existing patterns
• ❌ There's already similar code in the codebase
• ❌ Documentation is out of date or missing
• ❌ Code review finds major issues after implementation

Sound familiar?

✨ The Solution: AI-Powered Spec-Driven Development

SpecWeaver transforms your development workflow with a systematic, AI-powered approach that combines automated code analysis, intelligent architecture design, and multi-agent collaboration:

# Instead of diving straight into code...
/feature-new Add real-time WebSocket notifications

# You get AI-powered development automation:
✅ Best practices research (SOLID principles, design patterns)
✅ Intelligent codebase exploration (finds related features automatically)
✅ Automated architecture design (atomic phases with user approval)
✅ AI-driven code review (catches issues BEFORE coding)
✅ Phase-by-phase implementation (with mandatory quality gates)
✅ Automatic documentation generation (when feature is verified)

Result: Every feature becomes a learning experience with complete traceability, quality assurance, and knowledge preservation.

---

🚀 Quick Start

Installation

Install via Claude Code Plugin Marketplace:

1. In Claude Code, type /plugin
2. Select "Add marketplace" (option 3)
3. Enter: https://github.com/RoniLeor/specWeaver
4. Press Enter to add the marketplace
5. Select specweaver from the list
6. Click Install

That's it! Your AI development agents are now ready to use.

Build Your First Feature with AI Agents

# Start automated feature development with best practices
/feature-new Add user authentication with JWT

# The AI-powered workflow guides you through:
# → Research (SOLID principles, security patterns, JWT best practices)
# → Exploration (finds existing auth code in your codebase)
# → Architecture Design (atomic phases with your approval)
# → Implementation (automated review gates after each phase)
# → Documentation (auto-generated when feature is complete)

---

🎯 Why Choose SpecWeaver?

For Individual Developers

• Learn Best Practices: Every feature includes automated research on design patterns, SOLID principles, and industry standards
• Catch Bugs Early: AI-powered code review catches issues before they reach production
• Build Faster: Multi-agent collaboration automates tedious research and analysis tasks
• Document Automatically: Keep docs in sync with automated documentation generation

For Development Teams

• Consistent Architecture: Automated codebase exploration ensures new features match existing patterns
• Knowledge Preservation: Complete spec files create an audit trail for future developers
• Code Quality Assurance: Mandatory review gates prevent technical debt
• Faster Onboarding: New team members learn from past feature implementations

For Software Engineering Managers

• Predictable Delivery: Atomic phasing with clear milestones
• Quality Metrics: Confidence-based code review with measurable outcomes
• Risk Reduction: Design review catches architectural issues before implementation
• Team Productivity: AI agents handle routine tasks, developers focus on innovation

---

📋 Claude Code Commands for Feature Development

🏗️ Automated Development Workflow

Command	Description	Use When
/feature-new	Design and implement new features with research, exploration, atomic phases, and review gates	Building any new feature from scratch
/feature-bugfix	Systematic bug investigation and fixing with parallel analysis and solution research	Fixing bugs or unexpected behavior
/feature-refactor	Intelligent refactoring with complexity assessment and code reuse analysis	Improving code quality or architecture

🔍 What Each Command Does

/feature-new - Build Features Right with AI Agents

Problem: Starting from scratch often leads to inconsistent architecture and missed patterns.

Solution: AI-driven research and automated architecture design with phase-by-phase quality gates.

/feature-new Add real-time dashboard updates

Workflow:

1. 🔬 Research Phase - 4 parallel searches for best practices
2. 🗺️ Exploration Phase - Finds related features and patterns
3. 🏗️ Architecture Phase - Designs atomic phases (you approve each)
4. ✅ Design Review - Validates architecture BEFORE coding
5. 💻 Implementation - Phase-by-phase with review gates
6. 📚 Documentation - Auto-updated after user confirms it works

Output:

.claude/specs/new-dashboard-updates/
├── 00-research.md              # Best practices & patterns
├── 01-exploration.md           # Related features found
├── 03-overview.md              # Architecture design
├── 04-phase-websocket.md       # Phase 1 spec
├── 05-phase-subscriber.md      # Phase 2 spec
├── 03-design-review.md         # Design validation
└── 04-phase-websocket-review.md # Implementation reviews

---

/feature-bugfix - Fix Bugs Systematically with AI Analysis

Problem: Bug fixes often address symptoms instead of root causes.

Solution: AI-powered deep investigation with parallel code analysis and automated solution research.

/feature-bugfix memory-leak-in-processor

Workflow:

1. 🔍 Investigation - Parallel: code analysis + documentation context
2. 🎯 Clarification - You describe the bug symptoms
3. 🔬 Research - 4 parallel searches for solutions
4. 🏗️ Design - Atomic fix phases with your approval
5. ✅ Design Review - Validates fix strategy
6. 💻 Implementation - Phase-by-phase fixes with review gates
7. 🧪 Testing - You verify the fix works
8. 📚 Documentation - Updates docs with troubleshooting info

Output:

.claude/specs/bugfix-memory-leak/
├── 00-investigation.md         # Deep code analysis
├── 01-bug-report.md            # User-confirmed bug
├── 02-research.md              # Solution research
├── 03-solution-design.md       # Fix strategy
└── phase-1-fix-review.md       # Implementation reviews

---

/feature-refactor - Refactor Intelligently with AI-Guided Analysis

Problem: Refactoring often creates duplicate code or breaks existing functionality.

Solution: AI-powered complexity assessment with automated code reuse analysis and pattern detection.

/feature-refactor Extract service layer from monolithic handler

Workflow:

1. 🗺️ Understanding - Parallel: deep code analysis + docs review
2. 🧠 Complexity Assessment - Decides if research is needed:
   • LOW → Skip research, use existing patterns
   • MEDIUM → Asks if you want research
   • HIGH → Targeted research on specific topics
3. 🔍 Gap Analysis - Identifies what to change + finds code to reuse
4. 🏗️ Design - Atomic refactor phases (you approve each)
5. 💻 Implementation - Phase-by-phase with review gates
6. 📚 Documentation - Updates docs after you confirm it works

Output:

.claude/specs/refactor-handler/
├── 01-understanding.md         # Feature analysis
├── 00-research.md              # Targeted research (if needed)
├── 01-gap-analysis.md          # Changes + reuse strategy
├── 02-overview.md              # Refactor plan
└── phase-1-extract-review.md   # Implementation reviews

---

🤖 AI Agents for Development Automation

SpecWeaver uses 5 specialized AI agents that collaborate throughout the workflow:

Agent	Role	Model	When Used
🟡 code-explorer	Traces execution paths, maps architecture layers, finds patterns	sonnet	Understanding existing features
🟢 code-architect	Designs architectures, creates implementation blueprints	sonnet	Planning new features/refactors
🔴 code-reviewer	Reviews code for bugs, quality issues, project conventions	sonnet	Design validation & phase gates
🔵 code-consolidator	Creates/updates documentation, eliminates duplication	sonnet	Documentation after feature works
🔵 code-commit	Creates semantic commits, runs quality checks	sonnet	Committing changes

Multi-Agent Collaboration Patterns

These AI agents work together in intelligent workflows to automate your development process:

New Feature Development:

code-explorer → code-architect → code-reviewer (design) →
implementation → code-reviewer (per phase) → code-consolidator (docs)

Automated workflow: Explore → Design → Review → Build → Document

Bug Fix Workflow:

code-reviewer + code-consolidator (parallel investigation) →
code-architect (fix design) → code-reviewer (validation) →
implementation → code-reviewer (per phase) → code-consolidator (docs)

AI-powered analysis: Investigate → Plan → Validate → Fix → Update

Intelligent Refactoring:

code-explorer + code-consolidator (parallel understanding) →
code-reviewer (reuse analysis) → code-architect (refactor plan) →
implementation → code-reviewer (per phase) → code-consolidator (docs)

Smart automation: Understand → Analyze → Design → Refactor → Sync

---

🎯 Real-World Examples

Before SpecWeaver (Manual Development)

You: "I need to add WebSocket support for real-time updates"

# 4 hours of manual coding later...
❌ Forgot to handle disconnections
❌ Didn't follow existing WebSocket patterns in codebase
❌ Missed edge cases for concurrent connections
❌ No automated testing or validation
❌ Documentation out of date
❌ Manual code review finds 8 issues
❌ Wasted time reinventing solutions

After SpecWeaver (AI-Powered Development)

/feature-new Add WebSocket support for real-time updates

# AI-powered development automation:
✅ Automated research: WebSocket best practices + SOLID principles
✅ Intelligent codebase exploration: Finds existing WebSocket code
✅ AI-driven architecture design: Matches your existing patterns
✅ Automated code review: Catches design issues BEFORE coding
✅ Quality gates: Reviews each phase implementation automatically
✅ Documentation generation: Updates docs when feature is complete

# Complete audit trail with automated specs:
.claude/specs/new-websocket-updates/
├── 00-research.md              # WebSocket patterns, lifecycle, security
├── 01-exploration.md           # Found: app/api/websocket/detection.py
├── 03-overview.md              # 5 atomic phases designed
├── 04-phase-message-types.md   # Phase 1: Add message types
├── 05-phase-broadcaster.md     # Phase 2: Pub/sub broadcaster
├── 06-phase-endpoint.md        # Phase 3: FastAPI endpoint
├── 07-phase-frontend.md        # Phase 4: React hook
├── 08-phase-ui.md              # Phase 5: UI integration
├── 03-design-review.md         # ✅ Approved by AI reviewer
└── *-review.md files           # All phases ✅ Approved

Time saved: 3+ hours • Issues prevented: 12 potential bugs • Code quality: Automated validation at every step

---

⚡ How It Works

Execution Flow

graph TD
    A[User Request] --> B{Command Type}
    B -->|feature-new| C[Research Best Practices]
    B -->|feature-bugfix| D[Investigate Bug]
    B -->|feature-refactor| E[Understand Feature]

    C --> F[Explore Codebase]
    D --> F
    E --> F

    F --> G[Design Architecture]
    G --> H{Design Review}
    H -->|Issues Found| G
    H -->|Approved| I[Phase 1 Implementation]

    I --> J{Code Review}
    J -->|Issues Found| I
    J -->|Approved| K{More Phases?}

    K -->|Yes| L[Next Phase]
    L --> J
    K -->|No| M[User Testing]

    M --> N{Works?}
    N -->|No| I
    N -->|Yes| O[Auto Documentation]

Loading

Core Principles for Quality Software Development

1. 🔬 Research Before Design - Automated research on best practices, design patterns, and SOLID principles before architecting
2. 🗺️ Explore Before Building - AI-powered codebase exploration finds existing patterns and reusable code
3. 🏗️ Design Before Coding - Get architecture approved through automated code review first
4. ✅ Review Before Proceeding - Mandatory quality gates with AI-driven validation after each phase
5. 📚 Document After Success - Automated documentation generation when feature is verified and working

Key Features for Development Automation

• Parallel Execution - AI agents run research and codebase exploration simultaneously for faster results
• Incremental Design - Approve each atomic phase before automated design of the next phase
• Mandatory Review Gates - Can't proceed with issues ≥ 80% confidence from AI code review
• Code Reuse Analysis - Automated analysis prevents duplication by finding existing code patterns
• Smart Research - LOW complexity skips research, HIGH complexity gets targeted automated research
• Multi-Agent Collaboration - 5 specialized AI agents work together on different aspects of development
• Quality Assurance - Confidence-based filtering ensures only real issues are reported

---

🛠️ Advanced Usage

Custom Configuration

Override agent models in .claude/settings.local.json:

{
  "agents": {
    "code-explorer": {
      "model": "opus"
    },
    "code-reviewer": {
      "model": "sonnet-3.5"
    }
  }
}

CI/CD Integration

# .github/workflows/spec-validation.yml
name: Validate Specs

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check Spec Files
        run: |
          if [ -d ".claude/specs" ]; then
            echo "✅ Spec files found"
            find .claude/specs -name "*.md" -type f
          else
            echo "⚠️ No spec files - was this feature spec-driven?"
          fi

Team Workflows

For Code Reviews:

# Reviewer can read the spec trail
cat .claude/specs/new-{feature}/*.md

# See what was researched, designed, and approved
# Understand architectural decisions
# Verify implementation matches design

For Onboarding:

# New team member can learn from specs
ls .claude/specs/

# Each directory tells a story:
# - What problem was solved
# - What research was done
# - What architecture was chosen
# - What phases were implemented

---

📁 Spec File Structure

Every workflow creates detailed specification files:

.claude/specs/
├── new-{feature}/              # New features
│   ├── 00-research.md          # Best practices research
│   ├── 01-exploration.md       # Codebase exploration
│   ├── 03-overview.md          # Architecture overview
│   ├── 04-phase-*.md           # Atomic phase specs
│   ├── 03-design-review.md     # Design validation
│   └── *-review.md             # Implementation reviews
│
├── bugfix-{feature}/           # Bug fixes
│   ├── 00-investigation.md     # Code analysis
│   ├── 01-bug-report.md        # User-confirmed bug
│   ├── 02-research.md          # Solution research
│   ├── 03-solution-design.md   # Fix strategy
│   └── phase-*-review.md       # Fix reviews
│
└── refactor-{feature}/         # Refactors
    ├── 01-understanding.md     # Feature analysis
    ├── 00-research.md          # Targeted research (if needed)
    ├── 01-gap-analysis.md      # Changes + reuse strategy
    ├── 02-overview.md          # Refactor plan
    └── phase-*-review.md       # Refactor reviews

Spec File Benefits

• 📋 Audit Trail - Complete record of decisions
• 🧠 Knowledge Base - Learn from past features
• 👥 Team Alignment - Everyone understands the "why"
• 🔄 Consistency - Future features follow proven patterns
• 📚 Onboarding - New developers see how things were built

---

🔒 Security & Quality

Pre-Commit Checks

The code-commit agent automatically runs quality checks before committing:

Language	Formatter	Type Checker
Python	ruff format	pyright
TypeScript	npm run lint	tsc --noEmit
Rust	cargo fmt	cargo clippy
Go	gofmt	staticcheck
Java	google-java-format	checkstyle

Confidence-Based Review

The code-reviewer agent only reports issues with ≥80% confidence:

• ✅ Eliminates false positives
• ✅ Focuses on issues that truly matter
• ✅ Respects your time

Mandatory Review Gates

Every phase must pass code review before proceeding:

Phase N Implementation
    ↓
Code Review (code-reviewer)
    ↓
Issues Found (≥80%)? → Fix → Re-review (loop)
    ↓
Approved → Phase N+1

You cannot skip review gates or proceed with unresolved issues.

---

📚 Documentation

• Agent Reference - Detailed agent descriptions and collaboration patterns
• Command Guide - Complete command documentation
• Examples - Real-world usage examples
• Contributing - How to contribute

---

🤝 Contributing

We welcome contributions! Here's how:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)
3. 💻 Make your changes
4. ✅ Test thoroughly
5. 📝 Update documentation
6. 🚀 Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

---

📄 License

MIT License - see LICENSE for details

---

🙏 Acknowledgments

• Built for Claude Code by Anthropic
• Inspired by spec-driven development and systematic engineering practices
• Thanks to all contributors and users

---

⭐ Star this repo if SpecWeaver improved your workflow!

Built with ❤️ by the SpecWeaver team

Report Bug • Request Feature • Discussions