Serena Workflow Engine

21-state workflow engine for Claude Code with Serena memory persistence, swarm coordination, and RLVR learning.

Prerequisites

• Node.js 18+ (LTS recommended) and npm 9+
• Claude Code installed globally

# Install claude-flow globally (required for swarm coordination and RLVR learning)
npm install -g claude-flow@alpha

# Verify installation
claude-flow --version

Install

1. Install MCP servers

claude mcp add claude-flow -s local -- npx claude-flow@v3alpha mcp start
claude mcp add sequential-thinking -s local -- npx -y @modelcontextprotocol/server-sequential-thinking
claude mcp add playwright -s local -- npx -y @playwright/mcp@latest
claude mcp add ruv-swarm -s local -- npx -y ruv-swarm mcp start

2. Install the plugin

claude plugin marketplace add https://github.com/EarthmanWeb/serena-workflow-engine.git
claude plugin install swe@EarthmanWeb --scope local

3. Enable auto-update

In Claude Code CLI: claude /plugin → Marketplaces tab → EarthmanWeb → Enable auto-update

4. Restart Claude Code and initialize

/swe-init

5. Restart Claude Code and Onboard your first feature

/swe-feature-onboard FEATURE_[KEY]

Custom Memory Paths

Create .serena/memory-paths.conf in your project root (one path per line):

./.serena/swe
./docs

Plugin bundled memories are always appended automatically. See MCP-README.md for details.

Commands

Command	Description
/swe-init	First-time setup
/swe-status	Show current state
/swe-feature-onboard [KEY]	Register existing feature
/swe-scaffold	Scaffold new project
/swe-reset	Reset workflow
/swe-goto [STATE]	Force transition (debug)
/swe-cleanup	Archive completed work

Troubleshooting

Stale plugin or Serena version

rm -rf ~/.cache/uv/environments-v2/ ~/.cache/uv/git-v0/ ~/.cache/uv/builds-v0/
rm -rf ~/.claude/plugins/cache/EarthmanWeb/
claude plugin marketplace add https://github.com/EarthmanWeb/serena-workflow-engine
claude plugin install swe@EarthmanWeb --scope local

Restart Claude Code.

Debug

claude --debug

---

Contributing

Local dev setup

git submodule update --init .claude/plugins/serena-workflow-engine
bash .claude/plugins/serena-workflow-engine/scripts/install-hooks.sh

Dual-location architecture

Location	Path	Purpose
Plugin folder	.claude/plugins/serena-workflow-engine/	Generic/portable code
Local memories	.serena/swe/	Project-specific adaptations

See memories/REF_SWE_DEVELOPMENT.md for full development standards.

License

MIT