blue/docs/rfcs/0002-port-coherence-functionality.md

RFC 0002: Port Coherence Functionality

Status	In Progress
Date	2026-01-24
Source Spike	blue-feature-gap-analysis

---

Summary

Port the essential functionality from coherence-mcp to blue, maintaining Blue's voice and philosophy while gaining the workflow capabilities that make coherence useful.

Problem

Blue currently has ~2% of coherence-mcp's functionality:

• 3 MCP tools (vs 35)
• 0 handler modules (vs 28)
• ~50 LOC core (vs 8,796)
• 0 database tables (vs 14)

Without these capabilities, blue can't manage RFCs, track work, or provide meaningful project status.

Proposal

Port coherence-mcp in 4 phases, adapting to Blue's voice throughout.

Phase 1: Foundation

Goal: Basic document management and persistence.

Component	Source	Target	Notes
store.rs	alignment-core	blue-core	Rename tables, Blue voice in errors
documents.rs	alignment-core	blue-core	Keep existing Blue structs, add methods
state.rs	alignment-core	blue-core	ProjectState → BlueState
repo.rs	alignment-core	blue-core	detect_alignment → detect_blue
workflow.rs	alignment-core	blue-core	Status transitions

Database schema:

• documents, document_links, tasks, worktrees, metadata
• FTS5 for search
• Schema version 1 (fresh start, not migrating from coherence)

MCP tools (Phase 1):

• blue_status
• blue_next
• blue_rfc_create
• blue_rfc_get
• blue_rfc_update_status
• blue_rfc_plan
• blue_rfc_validate
• blue_rfc_complete
• blue_rfc_task_complete

Phase 2: Workflow

Goal: Full RFC/Spike/ADR lifecycle + PR workflow.

Component	Source	Target
rfc.rs	handlers	blue-mcp/handlers
spike.rs	handlers	blue-mcp/handlers
adr.rs	handlers	blue-mcp/handlers
decision.rs	handlers	blue-mcp/handlers
worktree.rs	handlers	blue-mcp/handlers
pr.rs	handlers	blue-mcp/handlers
release.rs	handlers	blue-mcp/handlers
search.rs	handlers	blue-mcp/handlers

MCP tools (Phase 2):

• blue_spike_create, blue_spike_complete
• blue_adr_create, blue_decision_create
• blue_worktree_create, blue_worktree_list, blue_worktree_remove
• blue_pr_create, blue_pr_verify, blue_pr_check_item, blue_pr_merge
• blue_release_create
• blue_search

Phase 3: Advanced

Goal: Multi-agent coordination and reminders.

Component	Source	Target
staging.rs	handlers	blue-mcp/handlers
reminder.rs	handlers	blue-mcp/handlers
session.rs	handlers	blue-mcp/handlers
env.rs	handlers	blue-mcp/handlers

Database additions:

• staging_locks, staging_lock_queue, staging_deployments
• active_sessions
• reminders

Phase 4: Specialized

Goal: Code intelligence and quality tools.

Component	Source	Target
code_store.rs	alignment-core	blue-core
symbol_extractor.rs	alignment-core	blue-core
lint.rs	handlers	blue-mcp/handlers
audit.rs	handlers	blue-mcp/handlers
guide.rs	handlers	blue-mcp/handlers

What NOT to Port

• Parked/Gated items - Half-implemented in coherence, skip for now
• Post-mortems/Runbooks - Low usage, add later if needed
• Dialogue tools - Specialized, port only if needed
• Infrastructure indexing - Complex, defer to Phase 5

Blue's Voice Adaptation

All ported code must speak as Blue:

// Coherence style
return Err(ServerError::AlignmentNotDetected);

// Blue style
return Err(ServerError::NotHome("Can't find Blue here. Run 'blue init' first?"));

// Coherence message
"RFC created successfully"

// Blue message
"Created RFC '{}'. Want me to help fill in the details?"

Directory Structure After Port

blue/
├── crates/
│   └── blue-core/
│       ├── src/
│       │   ├── lib.rs
│       │   ├── documents.rs    # Document types
│       │   ├── store.rs        # SQLite persistence
│       │   ├── state.rs        # Project state
│       │   ├── repo.rs         # Git operations
│       │   ├── workflow.rs     # Status transitions
│       │   ├── voice.rs        # Blue's tone (existing)
│       │   └── search.rs       # FTS5 search
│       └── Cargo.toml
│   └── blue-mcp/
│       ├── src/
│       │   ├── lib.rs
│       │   ├── server.rs       # MCP server
│       │   ├── error.rs        # Error types
│       │   ├── tools.rs        # Tool definitions
│       │   └── handlers/
│       │       ├── mod.rs
│       │       ├── rfc.rs
│       │       ├── spike.rs
│       │       ├── adr.rs
│       │       ├── worktree.rs
│       │       ├── pr.rs
│       │       ├── search.rs
│       │       └── ...
│       └── Cargo.toml
└── apps/
    └── blue-cli/

Goals

1. Feature parity with coherence-mcp core workflow
2. Blue's voice and philosophy throughout
3. Fresh schema (no migration baggage)
4. Cleaner code structure from lessons learned

Non-Goals

1. 100% feature parity (skip rarely-used features)
2. Backward compatibility with coherence databases
3. Supporting both alignment_ and blue_ tool names

Implementation Progress

Phase 1: Foundation - COMPLETE

• store.rs - SQLite persistence with schema v1, WAL mode, FTS5 search
• documents.rs - Rfc, Spike, Adr, Decision with markdown generation
• state.rs - ProjectState with active/ready/stalled/draft items
• repo.rs - detect_blue(), worktree operations
• workflow.rs - RfcStatus, SpikeOutcome, transitions
• 9 MCP tools: blue_status, blue_next, blue_rfc_create, blue_rfc_get, blue_rfc_update_status, blue_rfc_plan, blue_rfc_validate, blue_rfc_task_complete, blue_search
• 14 unit tests passing
• Blue's voice in all error messages

Phase 2: Workflow - COMPLETE

• handlers/spike.rs - Spike create/complete with RFC enforcement
• handlers/adr.rs - ADR creation with RFC linking
• handlers/decision.rs - Lightweight Decision Notes
• handlers/worktree.rs - Git worktree operations
• 7 new MCP tools: blue_spike_create, blue_spike_complete, blue_adr_create, blue_decision_create, blue_worktree_create, blue_worktree_list, blue_worktree_remove
• Total: 16 MCP tools, 842 new lines of code
• Blue's voice in all error messages

Phase 3: PR and Release - COMPLETE

• handlers/pr.rs - PR create, verify, check_item, check_approvals, merge
• handlers/release.rs - Semantic versioning release creation
• 6 new MCP tools: blue_pr_create, blue_pr_verify, blue_pr_check_item, blue_pr_check_approvals, blue_pr_merge, blue_release_create
• Total: 22 MCP tools
• Blue's voice in all error messages
• 16 tests passing

Phase 4: Session and Reminders - COMPLETE

• store.rs - Added session and reminder tables, schema v2
• handlers/session.rs - Session ping (start/heartbeat/end) + list
• handlers/reminder.rs - Reminder CRUD with gates, snoozing, clearing
• voice.rs - Added info() function for informational messages
• 6 new MCP tools: blue_session_ping, blue_session_list, blue_reminder_create, blue_reminder_list, blue_reminder_snooze, blue_reminder_clear
• Total: 28 MCP tools
• Blue's voice in all error messages
• 21 tests passing

Phase 5: Staging Locks - COMPLETE

• store.rs - Added staging_locks and staging_lock_queue tables
• handlers/staging.rs - Lock/unlock/status/cleanup for multi-agent coordination
• 4 new MCP tools: blue_staging_lock, blue_staging_unlock, blue_staging_status, blue_staging_cleanup
• Total: 32 MCP tools
• Blue's voice in all error messages
• 24 tests passing

Phase 6: Pending (Future)

Remaining tools to port (if needed):

• Code search/indexing (requires tree-sitter)
• IaC detection and staging deployment tracking

Test Plan

• blue init creates .blue/ directory structure
• blue rfc create persists to SQLite
• blue status shows active/ready/stalled items
• blue search finds documents by keyword
• Blue's voice in all error messages
• Worktree operations work with git

---

"Right then. Quite a bit to port. But we'll take it step by step."

— Blue