beads/TESTING_NEXT.md

Claude Code Plugin Testing - Handoff Document

Status: Plugin implementation complete, ready for testing Date: 2025-10-14 Session: Plugin development and version management

What Was Completed This Session

1. Claude Code Plugin (GitHub #28, bd-52)

✅ Created complete plugin structure in .claude-plugin/:

• plugin.json - Metadata with MCP server configuration
• marketplace.json - Local marketplace config
• 9 slash commands in commands/
• 1 agent in agents/

✅ Slash commands implemented:

• /bd-ready - Find ready work
• /bd-create - Create issues interactively
• /bd-show - Show issue details
• /bd-update - Update issues
• /bd-close - Close issues
• /bd-workflow - Show workflow guide
• /bd-init - Initialize beads
• /bd-stats - Project statistics
• /bd-version - Version compatibility checking

✅ Documentation:

• PLUGIN.md - Complete plugin documentation
• Updated README.md with plugin section
• Updated examples/README.md

2. Version Management (bd-66, bd-67)

✅ Fixed version inconsistencies:

• All components synced to 0.9.2
• bd CLI, Plugin, MCP server, README, PLUGIN.md

✅ Created scripts/bump-version.sh:

• Automated version syncing across all files
• Validates semantic versioning
• Shows diff preview
• Auto-commit option

✅ Updated CLAUDE.md:

• Added "Version Management" section
• Instructions for future agents on version bumps
• Common user phrases to recognize

3. Code Review

✅ Comprehensive review identified and fixed:

• Commands were in wrong location (moved to .claude-plugin/)
• All issues addressed from review

What Needs Testing (bd-64)

Critical Tests

1. Plugin Installation

   /plugin marketplace add steveyegge/beads
   /plugin install beads
   # Restart Claude Code
   

2. Slash Commands

   /bd-version        # Should show 0.9.2
   /bd-workflow       # Show workflow
   /bd-stats          # Project stats
   /bd-ready          # Find work
   /bd-create "Test" task 2
   

3. MCP Server

   /mcp               # Verify 'beads' appears
   

4. Task Agent

   @task-agent        # If supported
   

Potential Issues to Watch For

1. MCP Server Path

   • Uses ${CLAUDE_PLUGIN_ROOT} variable
   • May need adjustment if not supported

2. Prerequisites

   • Requires bd CLI in PATH
   • Requires uv for Python MCP server

3. Agent Syntax

   • Task agent syntax may differ from @task-agent
   • May need adjustment based on Claude Code version

Important Files for Next Agent

Key Implementation Files

• .claude-plugin/plugin.json - Plugin metadata
• .claude-plugin/commands/*.md - All 9 slash commands
• .claude-plugin/agents/task-agent.md - Autonomous agent
• PLUGIN.md - Complete documentation
• scripts/bump-version.sh - Version management script

Key Documentation Files

• CLAUDE.md - READ THIS FIRST - Has version management instructions
• PLUGIN.md - Plugin user documentation
• scripts/README.md - Script documentation
• bd-64 issue notes - Detailed testing instructions

Commit History (for context)

a612b92 - docs: Add version management to CLAUDE.md
a5c71f0 - feat: Add version bump script
c0f1044 - fix: Sync all component versions to 0.9.2
d25fc53 - feat: Add version compatibility checking
9f38375 - feat: Add Claude Code plugin for beads

How to Continue

Immediate Next Steps

1. Read bd-64 notes (has complete testing instructions)
2. Install plugin from GitHub
3. Test all slash commands
4. Document any issues found
5. Fix issues or update documentation
6. Close bd-64 when testing complete

If Plugin Testing Succeeds

1. Update bd-64 with test results
2. Close bd-64
3. Consider announcing plugin availability
4. Update PLUGIN.md if any corrections needed

If Plugin Testing Fails

1. Document specific failures in bd-64
2. Create new issues for each problem
3. Link to bd-64 with discovered-from
4. Fix issues systematically
5. Retest

User Context

The user (Steve) is working rapidly on beads, fixing "dozens of major bugs a day" (his words). He wants:

1. Version Management: Clear process for version bumps

   • Just say "bump to X.Y.Z" and agent should use script
   • All versions must stay in sync

2. Plugin Testing: Real-world GitHub installation test

   • Not local, use steveyegge/beads marketplace
   • Document any issues for iteration

3. Clean Handoffs: Each session should leave clear instructions

   • What was done
   • What needs doing
   • How to do it

Important Notes

Version Bumping

When user says any of:

• "Bump to 0.9.3"
• "Update version to X.Y.Z"
• "Rev the project to X.Y.Z"
• "Increment the version"

You should:

./scripts/bump-version.sh X.Y.Z --commit
git push origin main

See CLAUDE.md "Version Management" section for details.

Plugin Development Status

• Structure: Complete ✅
• Implementation: Complete ✅
• Documentation: Complete ✅
• Testing: Not started ⏳
• Release: Pending testing results

Known Limitations

1. MCP server uses ${CLAUDE_PLUGIN_ROOT} - may need verification
2. Task agent syntax untested
3. Plugin requires separate bd CLI installation
4. No icon for marketplace (nice-to-have)

Questions for Testing Agent

While testing, please document:

1. Did plugin install successfully from GitHub?
2. Did all slash commands work?
3. Did MCP server connect?
4. Were there any error messages?
5. Is documentation accurate?
6. What needs improvement?

Success Criteria

Plugin is ready for users when:

• ✅ Installs via /plugin install beads
• ✅ All 9 slash commands work
• ✅ MCP server connects and tools accessible
• ✅ Version checking works correctly
• ✅ Documentation is accurate
• ✅ No major bugs or blocking issues

Where We Are in the Bigger Picture

This plugin work relates to:

• GitHub Issue #28: Claude Code plugin request
• bd-52: Main plugin epic (now complete)
• bd-64: Testing task (next up)
• Goal: Make beads easy to install and use in Claude Code

The plugin leverages the existing MCP server (integrations/beads-mcp/) which is mature and tested. We're just packaging it nicely for Claude Code users.

---

Next Agent: Start by reading bd-64 notes, then test the plugin from GitHub. Good luck! 🚀