Serena Workflow Engine
A 14-state workflow engine plugin for Claude Code. Provides structured task routing, Serena memory persistence, hook-driven automation, and optional multi-agent swarm orchestration.
Quick Start
1. Install
claude plugin marketplace add https://github.com/EarthmanWeb/serena-workflow-engine.git
claude plugin install swe@EarthmanWeb --scope local
Install with --scope local for a single project, or --scope user to make it available globally across all projects. When installed globally, hooks are inert in projects that haven't been initialized -- they won't interfere until you run /swe-init.
Auto-update is built in: the plugin checks for the latest version on session start via the marketplace hook.
2. Initialize
Restart Claude Code, then run:
/swe-init
This launches an autonomous agent that handles everything:
- Detects your project's languages and test framework
- Creates
.serena/ directory structure and config files
- Renders template memories with auto-detected project values (project name, language, test runner, etc.)
- Migrates existing auto-memory files from
~/.claude/projects/.../memory/ into .serena/memory/ with structured subdirectories, then creates a symlink so future auto-memory writes go directly to .serena/memory/
- Injects
CLAUDE.md with memory storage directives pointing to .serena/memory/
- Sets up and verifies MCP servers (Serena + swe-wm)
- Installs language servers for detected languages
- Configures
.gitignore for runtime exclusions
Designed to work with the VSCode extension version of Claude Code -- it uses the same auto-memory path that the extension expects for the symlink.
Init is idempotent -- safe to re-run if interrupted.
3. Onboard a feature
Restart Claude Code, then:
/swe-feature-onboard [KEY]
Example: /swe-feature-onboard BACKEND
Features define the scope, file paths, and architecture patterns the workflow uses when routing tasks.
How It Works
Every session follows a structured flow:
WF_START -> WF_CLASSIFY -> WF_ARCH_REVIEW -> WF_EXECUTE -> WF_VERIFY -> WF_DONE
- WF_CLASSIFY loads feature memories and routes by task type
- WF_ARCH_REVIEW designs the plan, checks compliance, gets approval
- WF_EXECUTE does the work with automatic checkpoints every 3 edits
- WF_VERIFY validates against architecture and compliance rules
Side paths: WF_RESEARCH (read-only exploration), WF_CONTINUE (resume previous work), WF_SWARM_ORCHESTRATE (multi-agent tasks), WF_DEBUG_TDD (test-driven debugging).
Memory Architecture
Storage Locations
| Path | Purpose |
|---|
.serena/memory/ | Project memories (features, domain, refs, specs) -- persisted, committed |
.serena/memories/ | Working Memory files (WM_<session>.md) -- ephemeral, gitignored |
.serena/memory-paths.conf | Serena memory path config |
Auto-Memory Symlink
The init sequence creates a symlink from ~/.claude/projects/<encoded>/memory/ to .serena/memory/. This redirects Claude Code's auto-memory system so all memory files are stored in the project repo instead of a global directory. The MEMORY.md index is also migrated and updated with new paths.
Working Memory MCP Server (swe-wm)
The plugin installs its own lightweight MCP server (swe-wm) for automated Working Memory management. It:
- Provides
swe_wm_read, swe_wm_update_section, and swe_wm_update_status tools
- Filters WM files from
list_memories output (accessed via swe-wm, not Serena)
- Auto-includes the plugin's hardcoded
WF_* workflow instruction files in read-only format from the plugin's cached install folder
Custom Memory Paths
Edit .serena/memory-paths.conf to add extra directories Serena should access (one path per line):
./.serena/memory
./.serena/memories
./docs:ro
./src/config:ro
Append :ro for read-only access. The first two paths are always present.
Template Rendering
Bootstrap auto-detects project info and fills template placeholders:
| Detected From | Values Filled |
|---|
package.json, composer.json, Cargo.toml | Project name, test framework, test commands |
| File extensions scan | Primary language, all languages |
| Dev dependencies | Test runner (Playwright, Jest, Vitest, PHPUnit, Pest, pytest, etc.) |
Templates rendered to .serena/memory/:
MEMORY.md -- memory index with default entriesFEATURE_TESTS.md -- test config with detected frameworkFEATURE_DEV_STANDARDS.md -- dev standards indexFEATURE_AGENTS.md -- agent registryfeedback/FEEDBACK_RESPONSE_FORMAT.md -- response styleref/REF_MCP_BROWSER_DEVTOOLS.md -- browser DevTools reference
Unresolved placeholders are left as-is for manual fill-out.
Auto-Memory Migration
When initializing a project that already has Claude Code auto-memory files, bootstrap automatically migrates, reorganizes, and symlinks them:
