stepwise-research

Stepwise Dev - Multi-Plugin Suite

A modular development workflow suite for Claude Code inspired by Ashley Ha's workflow, adapted to work 100% locally with thoughts.

📖 Read more: Tu CLAUDE.md no funciona sin Context Engineering (Spanish article about Stepwise-dev)

🎯 What This Is

Solves the context management problem: LLMs lose attention after 60% context usage.

Implements Research → Plan → Implement → Validate with frequent /clear and persistent thoughts/ storage.

Philosophy

• Keep context < 60% (attention threshold)
• Split work into phases
• Clear between phases, save to thoughts/
• Never lose research or decisions

📦 Available Plugins

This repository contains 4 independent plugins that can be installed separately based on your needs:

1. stepwise-core (Core Workflow)

The foundation plugin with the complete Research → Plan → Implement → Validate cycle.

Includes:

• 5 slash commands (research_codebase, create_plan, iterate_plan, implement_plan, validate_plan)
• 5 specialized agents (codebase exploration and thoughts management)
• 1 thoughts-management skill (with 3 bash scripts)

→ Read more

2. stepwise-git (Git Operations)

Clean git commit workflow without Claude attribution.

Includes:

• 1 slash command (commit)
• Smart staging and commit message generation

→ Read more

3. stepwise-web (Web Research)

Web search and research capabilities for external context.

Includes:

• 1 specialized agent (web-search-researcher)
• Deep web research with source citations

→ Read more

4. stepwise-research (Multi-Agent Deep Research)

Advanced multi-agent research system with parallel web searches and synthesis.

Includes:

• 1 slash command (deep_research)
• 3 specialized agents (research-lead, research-worker, citation-analyst)
• 1 research-reports skill (with report generation script)
• Comprehensive research reports with citations and metadata

→ Read more

🚀 Installation

Option 1: Install All Plugins (Recommended for first-time users)

# Add marketplace from GitHub
/plugin marketplace add nikeyes/stepwise-dev

# Install all plugins
/plugin install stepwise-core@stepwise-dev
/plugin install stepwise-git@stepwise-dev
/plugin install stepwise-web@stepwise-dev
/plugin install stepwise-research@stepwise-dev

Option 2: Install Only What You Need

# Add marketplace
/plugin marketplace add nikeyes/stepwise-dev

# Install only the core workflow
/plugin install stepwise-core@stepwise-dev

# Optionally add git operations
/plugin install stepwise-git@stepwise-dev

# Optionally add web research
/plugin install stepwise-web@stepwise-dev

# Optionally add multi-agent deep research
/plugin install stepwise-research@stepwise-dev

Restart Claude Code after installation.

🧪 Try It Out

Don't have a project to test with? Use stepwise-todo-api-test — a sample repository designed for testing these plugins.

📁 Directory Structure

After running thoughts-init (from stepwise-core) in a project:

<your-project>/
├── thoughts/
│   ├── nikey_es/          # Your personal notes (you write)
│   │   ├── tickets/       # Ticket documentation
│   │   └── notes/         # Personal notes
│   ├── shared/            # Team-shared documents (Claude writes)
│   │   ├── research/      # Research documents
│   │   ├── plans/         # Implementation plans
│   │   └── prs/           # PR descriptions
│   └── searchable/        # Hardlinks for grep (auto-generated)
│       ├── nikey_es/      # → hardlinks to nikey_es/
│       └── shared/        # → hardlinks to shared/
├── .gitignore            # (add thoughts/searchable/ to this)
└── ...

Key distinction:

• nikey_es/: Personal tickets/notes you create manually
• shared/: Formal docs Claude generates from commands

Why Hardlinks?

• Fast searching: Grep one directory instead of many
• No duplication: Same file, same inode, no extra disk space
• Auto-sync: Changes in source are immediately visible
• Efficient: Better than symlinks for grep operations

🔄 The Four-Phase Workflow

Phase 1: Research (stepwise-core)

/stepwise-core:research_codebase How does authentication work?

Spawns parallel agents, searches codebase and thoughts/, generates comprehensive research document.

Phase 2: Plan (stepwise-core)