Vespera Atelier Monorepo Development

Development guidance for working in the Vespera Atelier monorepo - an intelligent platform for document-centric orchestration, task management, and creative workflows.

Monorepo Structure

```

vespera-atelier/

├── packages/

│ ├── vespera-scriptorium/ # MCP task orchestrator backend

│ ├── vespera-atelier/ # Platform coordination services

│ └── vespera-utilities/ # Shared utility functions

├── plugins/

│ └── Obsidian/

│ └── Vespera-Scriptorium/ # Obsidian plugin frontend

├── PRPs/ # Product Requirement Prompts

├── docs/ # Comprehensive architecture documentation

│ ├── architecture/ # Core system architecture

│ ├── development/ # Development tracking and decisions

│ ├── examples/ # Automation rule examples

│ └── guides/ # User and developer guides

└── .claude/ # Claude Code configuration

```

Critical Directives

MCP Server Failure Protocol

**If the Vespera Scriptorium MCP server fails:**

1. **STOP** - Do not proceed with current task

2. **DIAGNOSE** - Check MCP connection and health:

```bash

cat ~/.claude.json | grep -A 5 vespera-scriptorium

cd packages/vespera-scriptorium

python3 mcp_server.py

```

3. **FIX** - Ask user to reconnect: `/mcp reconnect vespera-scriptorium`

4. **VERIFY** - Test with `mcp__vespera-scriptorium__health_check` tool

5. **RESUME** - Only continue after verification

Architecture Documentation First

**Before ANY development work:**

1. Check the Component Development Guide

2. Read required architectural documents for your component

3. Understand the template-driven, Codex-based system design

4. Never hardcode content types - everything is template-driven

5. Reference `docs/architecture/` for technical specifications

Git Commit After Every Task

**After completing ANY development task:**

1. Review changes: `git status && git diff`

2. Commit with descriptive message including package scope: `feat(scriptorium): description`

3. Never leave uncommitted changes between tasks

Phase Handover Process

**When completing a phase:**

1. Use `/phase-complete` command for comprehensive phase documentation

2. Fill out `PHASE_[N]_COMPLETE.md` with ALL sections

3. Focus on "Context for AI Assistant" section for next sessions

4. Create related ADRs for significant decisions

5. Use `/handover` command for quick context transitions

Working in the Monorepo

Automatic Directory Switching

**Claude Code automatically switches to `packages/vespera-scriptorium`** as working directory due to workspace configuration.

```bash

For monorepo root operations, be explicit:

cd /home/aya/dev/monorepo/vespera-atelier && [command]

Or use absolute paths:

ls /home/aya/dev/monorepo/vespera-atelier/PRPs/

Check current directory:

pwd

```

Package-Specific Development

```bash

Navigate to package

cd packages/vespera-scriptorium

Install dependencies

pip install -e .

Run tests

pytest tests/

```

Cross-Package Development

```bash

From monorepo root

pnpm build # Build all packages

pnpm test # Test all packages

pnpm scriptorium:dev # Run specific package

```

MCP Server Configuration

Vespera Scriptorium (Bindery Integration)

The MCP server in `packages/vespera-scriptorium/` uses FastMCP as a translation layer to the Rust Bindery backend.

```bash

Install dependencies

cd packages/vespera-scriptorium

pip install -r requirements.txt

Run MCP server directly (testing)

python3 mcp_server.py

Add to Claude Code (user scope)

claude mcp add -s user vespera-scriptorium python3 /path/to/vespera-atelier/packages/vespera-scriptorium/mcp_server.py

Reconnect in active session

/mcp reconnect vespera-scriptorium

```

**14 MCP Tools Available:**

Development Best Practices

Component Refactoring Strategy

**DO NOT** create simplified/alternative versions of existing components.

**DO** modularize complex components by breaking them into smaller pieces.

```typescript

// ✅ GOOD: Modularizing complex component

// CodexEditor.tsx (main orchestrator)

// ├── CodexEditorHeader.tsx (extracted module)

// ├── CodexEditorFields.tsx (extracted module)

// └── hooks/

// ├── useCodexState.ts (extracted logic)

// └── useCodexValidation.ts (extracted logic)

```

Template Development Standards

Templates are the core of the system:

1. Standardize schemas first before implementing dependent features

2. Create defined subcomponents that templates can contain

3. Implement validation with clear error messages

4. Add fallback behavior for edge cases

5. Document template patterns for consistency

Performance Considerations

Collaborative Editing

Consider Bindery CRDT infrastructure:

Essential Commands

Monorepo Operations

```bash

pnpm install # Install all dependencies

pnpm build # Build all packages

pnpm test # Run all tests

pnpm lint # Lint all packages

```

Vespera Scriptorium Operations

```bash

cd packages/vespera-scriptorium

pip install -r requirements.txt # Install dependencies

python3 mcp_server.py # Run MCP server

pytest # Run unit tests

python3 run_mcp_tests.py # Run MCP integration tests

black *.py # Format code

isort *.py # Sort imports

```

Testing Commands

```bash

cd packages/vespera-scriptorium

All tests

pytest

python3 run_mcp_tests.py

Specific test suites

pytest test_bindery_tools_mock.py # Bindery integration

pytest test_mcp_server_complete.py # MCP server completeness

pytest test_integrated_backend.py # Backend integration

```

Git Operations

```bash

git add packages/

git commit -m "feat(scriptorium): description"

```

Custom Slash Commands

Key Documentation References

Architecture Patterns

Vespera Scriptorium Architecture

1. **MCP Server Mode**: FastMCP server with 14 comprehensive tools

2. **Translation Layer**: Python MCP server translates calls to Rust Bindery HTTP API

3. **Backend Integration**: Communicates with Rust Bindery backend

4. **Security & Resilience**: Structured error handling, validation, retry logic

Core Components

**MCP Server:**

**Testing:**

Quick Start

1. **Clone and Setup**:

```bash

cd /path/to/vespera-atelier

pnpm install

```

2. **Install Vespera Scriptorium**:

```bash

cd packages/vespera-scriptorium

pip install -r requirements.txt

```

3. **Test System**:

```bash

pytest

python3 run_mcp_tests.py

```

4. **Configure MCP**:

```bash

claude mcp add -s user vespera-scriptorium python3 $(pwd)/packages/vespera-scriptorium/mcp_server.py

```

Key Concepts