Add stepwise-research plugin: Multi-agent deep research system

[nikeyes]

Summary

Implements a comprehensive multi-agent research plugin inspired by Anthropic's Claude.ai Research system. Research shows this architecture achieves 90.2% better results than single-agent approaches through parallel orchestration.

Key Features

• 🤖 Multi-agent orchestration - Lead researcher spawns 1-6+ workers based on query complexity
• ⚡ Parallel execution - Workers search simultaneously for faster results
• 📚 Comprehensive synthesis - Cross-references findings from multiple sources
• 🔍 Citation verification - Dedicated agent ensures accuracy and completeness
• 📝 Structured reports - Markdown with YAML frontmatter and numbered citations
• 💾 Persistence - Saves to thoughts/ directory for future reference
• ✨ Zero dependencies - Uses built-in WebSearch/WebFetch tools

Architecture

Based on Anthropic's multi-agent research patterns:

1. deep_research command - Main orchestration workflow
2. research-lead agent (Opus) - Breaks query into sub-questions, spawns workers, synthesizes findings
3. research-worker agents (Sonnet) - Execute focused web searches in parallel
4. citation-analyst agent (Sonnet) - Verifies citation accuracy post-synthesis
5. research-reports Skill - Formats reports with YAML frontmatter and citations

Design Principles

• OODA Loop framework (Observe, Orient, Decide, Act)
• Broad-then-narrow search strategy (1-6 word queries → progressively refined)
• Source quality hierarchy (Tier 1: .gov/.edu → Tier 4: SEO farms)
• Independent contexts (each worker operates in 200K token context)
• Synthesis over concatenation (cross-reference and integrate findings)
• Post-synthesis verification (citation analyst runs after synthesis)

Components Added

New plugin directory: research/

research/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── deep_research.md
├── agents/
│   ├── research-lead.md
│   ├── research-worker.md
│   └── citation-analyst.md
├── skills/
│   └── research-reports/
│       ├── SKILL.md
│       └── scripts/
│           └── generate-report
└── README.md

Modified files:

• .claude-plugin/marketplace.json - Added stepwise-research plugin entry (v0.0.1)
• README.md - Updated to document 4 plugins (was 3)
• Makefile - Added research plugin manifest validation
• test/plugin-structure-test.sh - Updated to handle 3+ plugins

Testing

✅ All automated tests passing:

• 22 functional tests (thoughts-init, thoughts-sync, thoughts-metadata)
• 37 structure tests (plugin manifests, commands, agents, skills)
• JSON validation (all manifests valid)
• Shellcheck validation (all bash scripts)
• generate-report script tested with sample data

Installation & Usage

# Install plugin
/plugin marketplace add nikeyes/stepwise-dev
/plugin install stepwise-research@stepwise-dev
# Restart Claude Code

# Usage
/stepwise-research:deep_research <research topic>

Example Queries

Simple query (1 worker, ~15 minutes):

/stepwise-research:deep_research What is Docker and how does it work?

Comparison query (2-3 workers, ~20-25 minutes):

/stepwise-research:deep_research Compare React vs Vue.js for enterprise applications

Complex research (4-6+ workers, ~30-40 minutes):

/stepwise-research:deep_research Analyze the state of AI code generation tools in 2026

Report Output

Reports saved to thoughts/shared/research/[topic]-[date].md with structure:

---
title: Research on [Topic]
date: YYYY-MM-DD
query: [Original research question]
keywords: [extracted, key, terms]
status: complete
agent_count: N
source_count: M
---

# Research on [Topic]

## Executive Summary
[3-5 sentence overview]

## Detailed Findings
[Synthesized findings with citations [1] [2]]

## Conclusions
[Key takeaways]

## Bibliography
[1] Source Title - URL
[2] Another Source - URL
...

Performance Characteristics

• Token usage: 50K-150K depending on complexity (research shows 80% correlation with quality)
• Worker scaling: 1-8 agents based on query complexity
• Time: 10-45 minutes depending on query and worker count
• Cost optimization: Workers use Sonnet, lead uses Opus for synthesis

Integration

• Integrates with stepwise-core thoughts management system
• Reports auto-synced to thoughts/searchable/ via hardlinks
• YAML frontmatter enables metadata-based searching
• Compatible with existing stepwise workflow (Research → Plan → Implement → Validate)

Future Enhancements (Out of Scope)

• Memory persistence across context truncations
• Recursive depth-first exploration
• Multi-modal research (images, PDFs, videos)
• Custom source filters
• Interactive mid-research refinement

Test Plan

• All automated tests passing
• Manual test: Simple query (1 worker)
• Manual test: Comparison query (2-3 workers)
• Manual test: Complex research (4-6+ workers)
• Verify reports saved to thoughts/shared/research/
• Verify citation quality and URL accessibility
• Verify thoughts-sync integration

---

Closes: Related to deep research capability request
Type: Feature
Breaking changes: None