Claude Code Stepwise Dev Plugin

A development workflow 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.

6 Slash Commands for structured development
5 Specialized Agents for parallel research
3 Bash Scripts for local thoughts/ management
Built-in version tracking for team synchronization

Philosophy

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

📦 What's Included

Enhanced Planning with Vertical Slicing

The create_plan command guides you through creating implementation plans that emphasize:

Small safe steps using the Hamburger Method for vertical slicing
Progressive delivery patterns (dummy → dynamic, backend-only → full stack, etc.)
Learning vs Earning phases to separate research from value delivery
Complexity assessment to guide implementation decisions
Reversibility and rollback strategies for each phase

Plans are created interactively, with vertical slicing analysis before committing to detailed phases.

Slash Commands

Command	Description
`/stepwise-dev:research_codebase`	Research and document codebase comprehensively
`/stepwise-dev:create_plan`	Create detailed implementation plans iteratively
`/stepwise-dev:iterate_plan`	Update existing implementation plans
`/stepwise-dev:implement_plan`	Execute plans phase by phase with validation
`/stepwise-dev:validate_plan`	Validate implementation against plan
`/stepwise-dev:commit`	Create git commits (no Claude attribution)

Specialized Agents

Agent	Purpose
`codebase-locator`	Find WHERE code lives in the codebase
`codebase-analyzer`	Understand HOW code works
`codebase-pattern-finder`	Find similar patterns to model after
`thoughts-locator`	Discover documents in thoughts/
`thoughts-analyzer`	Extract insights from thoughts docs

Thoughts Scripts (Included in Plugin)

Script	Purpose
`thoughts-init`	Initialize thoughts/ structure in a project
`thoughts-sync`	Sync hardlinks in searchable/ directory
`thoughts-metadata`	Generate git metadata for documents

Note: These scripts are executed automatically by the thoughts-management Skill. You don't need to install them separately or configure PATH.

🚀 Installation

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

# Install plugin
/plugin install stepwise-dev@stepwise-dev

Restart Claude Code after installation.

That's it! The plugin includes:

6 slash commands
5 specialized agents
1 thoughts-management Skill (with 3 bash scripts)

All components are ready to use immediately after installation.

🧪 Try It Out

Don't have a project to test with? Use stepwise-todo-api-test — a sample repository with small and large tasks designed for testing this plugin in an isolated environment.

📁 Directory Structure

After running thoughts-init 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
Example: /create_plan thoughts/nikey_es/tickets/eng_1234.md reads your ticket → writes shared/plans/2025-11-09-ENG-1234-*.md

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

Thoughts Directory

This directory contains research documents, implementation plans, and notes for this project.

Structure

nikey_es/ - Personal notes and tickets
- tickets/ - Ticket documentation and tracking
- notes/ - Personal notes and observations
shared/ - Team-shared documents
- research/ - Research documents from /stepwise-dev:research_codebase
- plans/ - Implementation plans from /stepwise-dev:create_plan
- prs/ - PR descriptions and documentation
searchable/ - Hardlinks for efficient grep searching (auto-generated)

Usage

Use Claude Code slash commands:

/stepwise-dev:research_codebase [topic] - Research and document codebase
/stepwise-dev:create_plan [description] - Create implementation plan
/stepwise-dev:implement_plan [plan-file] - Execute a plan
/stepwise-dev:validate_plan [plan-file] - Validate implementation

Run thoughts-sync after adding/modifying files to update searchable/ hardlinks.

🔄 The Four-Phase Workflow

Phase 1: Research

Goal: Understand what exists before changing anything.

# In Claude Code
/stepwise-dev:research_codebase How does authentication work in this app?

This will:

Spawn parallel agents to search the codebase
Search thoughts/ for historical context
Generate a comprehensive research document
Save to thoughts/shared/research/YYYY-MM-DD-topic.md
Run thoughts-sync to update searchable/

Output: Research document with code references, architecture insights, and file:line numbers.

Phase 2: Plan

Goal: Create a detailed, iterative implementation plan.

# In Claude Code
/stepwise-dev:create_plan Add rate limiting to the API
# Or reference a research doc:
/stepwise-dev:create_plan @thoughts/shared/research/2025-11-09-auth-system.md

This will:

Ask clarifying questions
Research existing patterns in the codebase
Iterate with you 5+ times on the plan
Create phases with specific changes
Define automated AND manual success criteria
Save to thoughts/shared/plans/YYYY-MM-DD-topic.md

Output: Detailed plan with phases, file paths, code snippets, and verification steps.

Phase 3: Implement

Goal: Execute one phase at a time with confidence.

# In Claude Code
/stepwise-dev:implement_plan @thoughts/shared/plans/2025-11-09-rate-limiting.md

This will:

Read the complete plan
Implement Phase 1
Run automated verification (tests, linting)
Pause for manual verification
Wait for your confirmation
Proceed to Phase 2 (or stop)

Key Rule: One phase at a time. Validate before proceeding.

Phase 4: Validate

Goal: Systematically verify the entire implementation.

# In Claude Code
/stepwise-dev:validate_plan @thoughts/shared/plans/2025-11-09-rate-limiting.md

This will:

Check all phases are complete
Run all automated verification
Review code against plan
Identify deviations or issues
Generate validation report

Output: Report showing what passed, what needs fixing, and manual test checklist.

💡 Usage Examples

Example 1: Feature Development

# 1. Research
/stepwise-dev:research_codebase Where is user registration handled?
# → Saves to thoughts/shared/research/2025-11-09-user-registration.md
# → /context shows 45%
# → /clear

# 2. Plan
/stepwise-dev:create_plan Add OAuth login support
# → Iterates 5 times
# → Saves to thoughts/shared/plans/2025-11-09-oauth-login.md
# → /context shows 58%
# → /clear

# 3. Implement (Phase 1 only)
/stepwise-dev:implement_plan @thoughts/shared/plans/2025-11-09-oauth-login.md
# → Completes Phase 1
# → Runs tests
# → Pauses for manual testing
# → You verify it works
# → "Continue to Phase 2"
# → /context shows 62%
# → /clear

# 4. Validate
/stepwise-dev:validate_plan @thoughts/shared/plans/2025-11-09-oauth-login.md
# → Comprehensive verification
# → /context shows 41%

# 5. Commit
/stepwise-dev:commit
# → Creates atomic commits

Example 2: Bug Investigation

# Research the bug
/stepwise-dev:research_codebase Why are webhooks timing out after 30 seconds?

# Create a fix plan
/stepwise-dev:create_plan Fix webhook timeout issue based on @thoughts/shared/research/...md

# Implement the fix
/stepwise-dev:implement_plan @thoughts/shared/plans/...md

# Commit
/stepwise-dev:commit

Example 3: Iterating on a Plan

# You've created a plan but need to adjust it
/stepwise-dev:iterate_plan @thoughts/shared/plans/2025-11-09-feature.md

# Claude asks: What changes would you like to make?
# You: "Add error handling phase before deployment"

# Claude updates the plan in place

🛠️ Thoughts Scripts

thoughts-init

Initialize thoughts/ in current project:

cd ~/projects/my-app
thoughts-init

Creates structure, README, .gitignore, and runs initial sync.

thoughts-sync

Sync hardlinks in searchable/:

thoughts-sync

Run this:

After adding new .md files
After modifying file structure
If searchable/ seems out of sync

The scripts automatically run this after /research_codebase and /create_plan.

thoughts-metadata

Generate metadata for the current repo:

thoughts-metadata

Returns:

Current Date/Time (TZ): 2025-11-09 15:30:00 PST
ISO DateTime: 2025-11-09T23:30:00+0000
Date Short: 2025-11-09
Current Git Commit Hash: abc123...
Current Branch Name: main
Repository Name: my-app
Git User: nikey_es

Used internally by commands to populate frontmatter.

🏷️ Version Management

Checking Plugin Version

/plugin
# Check on Installed tab

Updating

/plugin -> Marketplaces tab -> stepwise-dev -> Update marketplace
/plugin -> Installed -> stepwise-dev -> Update now

Note: Plugin updates include commands, agents, and scripts automatically. No separate script installation needed.

📝 Context Management

Golden Rule: Never exceed 60% context capacity.

Check context frequently:

/context

Clear between phases:

/clear

🔧 Customization

Change Username: Set export THOUGHTS_USER=your_name or edit skills/thoughts-management/scripts/thoughts-init:8

Add Commands: Create .md files in ~/.claude/commands/ with frontmatter. Claude auto-detects on restart.

🧪 Testing

make test          # Run all automated tests (functional + structure)
make test-verbose  # Run tests with debug output
make check         # Run shellcheck on all bash scripts
make ci            # Run full CI validation (test + check + plugin)

Tests validate bash scripts (thoughts-init, thoughts-sync, thoughts-metadata) and plugin structure. No dependencies needed, runs in isolated temp directories.

Test structure:

test/thoughts-structure-test.sh - Functional tests for thoughts/ operations
test/plugin-structure-test.sh - Plugin structure validation
test/test-helpers.sh - Test utilities and assertions
test/commands/ - Test command definitions

🐛 Troubleshooting

Plugin Issues

Commands not showing after installation:

Restart Claude Code completely
Check plugin is enabled: /plugin list
Try reinstalling: /plugin uninstall stepwise-dev@stepwise-dev then /plugin install stepwise-dev@stepwise-dev

Plugin installation fails:

Verify marketplace added: /plugin marketplace list
Check network connection (for GitHub marketplaces)
Try local marketplace for testing: /plugin marketplace add ./test-marketplace

Workflow Issues

Hardlinks failing: Script auto-falls back to symlinks (slower but works)

No files synced: Run THOUGHTS_DEBUG=1 thoughts-sync to debug

Plugin version mismatch: Update plugin with /plugin update stepwise-dev@stepwise-dev. All components (commands, agents, scripts) update together.

📚 Learn More

Original Article: I mastered the Claude Code workflow by Ashley Ha
HumanLayer: Original inspiration from HumanLayer's .claude directory

🤝 Contributing

This is extracted from HumanLayer and adapted for local use. If you have improvements:

Test them in your workflow
Document what changed and why
Share with the community

📄 License

Apache License 2.0 - See LICENSE file for details.

🔖 Attribution

This project is derived from HumanLayer's Claude Code workflow under Apache License 2.0.

See NOTICE for detailed attribution.

Major enhancements and modifications:

Specialized agent system for efficient codebase exploration (5 custom agents)
Local-only thoughts/ management with Agent Skill (no cloud dependencies)
Automated testing infrastructure for bash scripts
Standalone plugin distribution system
Enhanced TDD-focused success criteria guidelines

🙏 Credits

Ashley Ha - For documenting and popularizing this workflow
HumanLayer Team (Dex Horthy et al.) - For creating the original commands and agents
Anthropic - For Claude Code

Happy Coding! 🚀

Questions? Issues? Open an issue on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 58 Commits
.claude-plugin		.claude-plugin
.claude		.claude
.github/workflows		.github/workflows
agents		agents
commands		commands
skills/thoughts-management		skills/thoughts-management
test		test
thoughts		thoughts
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md

License

nikeyes/stepwise-dev

Folders and files

Latest commit

History

Repository files navigation

Claude Code Stepwise Dev Plugin

🎯 What This Is

Philosophy

📦 What's Included

Enhanced Planning with Vertical Slicing

Slash Commands

Specialized Agents

Thoughts Scripts (Included in Plugin)

🚀 Installation

🧪 Try It Out

📁 Directory Structure

Why Hardlinks?

Thoughts Directory

Structure

Usage

🔄 The Four-Phase Workflow

Phase 1: Research

Phase 2: Plan

Phase 3: Implement

Phase 4: Validate

💡 Usage Examples

Example 1: Feature Development

Example 2: Bug Investigation

Example 3: Iterating on a Plan

🛠️ Thoughts Scripts

thoughts-init

thoughts-sync

thoughts-metadata

🏷️ Version Management

Checking Plugin Version

Updating

📝 Context Management

🔧 Customization

🧪 Testing

🐛 Troubleshooting

Plugin Issues

Workflow Issues

📚 Learn More

🤝 Contributing

📄 License

🔖 Attribution

🙏 Credits

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages