This file provides guidance to Claude Code when working in the Vespera Atelier monorepo.
Sign in to like and favorite skills
This file provides guidance to Claude Code when working in the Vespera Atelier monorepo.
This is a monorepo containing multiple interconnected packages:
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 āāā apps/ # Future applications āāā PRPs/ # Product Requirement Prompts āāā docs/ # Comprehensive architecture documentation ā āāā README.md # Documentation hub and navigation ā āāā architecture/ # Core system architecture documents ā ā āāā core/ # Foundation architecture (9 docs) ā ā ā āāā PROJECT_CENTRIC_ARCHITECTURE.md # Projects as fundamental ā ā ā āāā HIERARCHICAL_TEMPLATE_SYSTEM.md # Dynamic template system ā ā ā āāā CODEX_NESTING.md # Scrivener-style folders ā ā ā āāā CODEX_ARCHITECTURE.md # Universal content system ā ā ā āāā TEMPLATE_SYSTEM_ARCHITECTURE.md # Template implementation ā ā ā āāā DYNAMIC_AUTOMATION_ARCHITECTURE.md # Automation (planned) ā ā ā āāā ... ā ā āāā subsystems/ # Specialized components (7 docs) ā ā āāā integration/ # API specifications ā ā āāā testing/ # Test infrastructure ā āāā development/ # Development tracking and decisions ā ā āāā decisions/ # Architecture Decision Records (ADRs) ā ā āāā phases/ # Phase completion reports ā ā āāā reports/ # Technical investigations ā ā āāā environment/ # Development setup ā āāā examples/ # Automation rule examples ā āāā guides/ # User and developer guides ā āāā reference/ # Glossary and references ā āāā legacy/ # Aspirational/unimplemented docs āāā .claude/ # Claude Code configuration
Claude Code automatically switches to
as the working directory due to workspace configuration:packages/vespera-scriptorium
packages/vespera-scriptorium.claude/config.json# If you need monorepo root context, be explicit: cd /home/aya/dev/monorepo/vespera-atelier && [your command] # Or use absolute paths: ls /home/aya/dev/monorepo/vespera-atelier/PRPs/ # Check current directory when in doubt: pwd
When working on a specific package:
# Navigate to package (or Claude Code may auto-switch here) cd packages/vespera-scriptorium # Install dependencies pip install -e . # Run tests pytest tests/
When making changes across multiple packages:
# Use workspace commands from root pnpm build # Build all packages pnpm test # Test all packages pnpm scriptorium:dev # Run specific package
The MCP server is in
packages/vespera-scriptorium/# Install dependencies cd packages/vespera-scriptorium pip install -r requirements.txt # Run MCP server directly (for testing) python3 mcp_server.py # Claude Code MCP integration (configured in user scope) # Add to user config: claude mcp add -s user vespera-scriptorium python3 /path/to/vespera-atelier/packages/vespera-scriptorium/mcp_server.py # Reconnect in active session: # Use the /mcp reconnect vespera-scriptorium command in Claude Code
MCP Features:
If the Vespera Scriptorium MCP server ever fails to function:
# Check if server is configured cat ~/.claude.json | grep -A 5 vespera-scriptorium # Test server directly cd packages/vespera-scriptorium python3 mcp_server.py
/mcp reconnect vespera-scriptoriummcp__vespera-scriptorium__health_checkMCP Tools Available:
Before starting ANY development work:
After completing ANY development task:
git status && git difffeat(scriptorium): descriptionWhen completing a phase or handing over context:
/phase-complete/handoverCustom Slash Commands Available:
/phase-start/phase-complete/handover/context/adrSee: docs/development/phases/PHASE_TEMPLATE.md for the phase documentation template
# Development installation cd packages/vespera-scriptorium pip install -r requirements.txt # Run MCP server python3 mcp_server.py # Run tests pytest python3 run_mcp_tests.py # Linting and formatting black *.py isort *.py
# Install workspace dependencies pnpm install # Build all packages pnpm build # Run specific package commands pnpm --filter vespera-atelier dev
Vespera Scriptorium implements a FastMCP-based translation layer to the Rust Bindery backend:
MCP Server:
mcp_server.pymodels.pybindery_client.pybackend_manager.pysecurity.pyresilience.pyTesting:
conftest.pytest_*.pyrun_mcp_tests.pyIMPORTANT: When encountering complex components that need refactoring:
ā DO NOT create simplified/alternative versions of existing components ā DO modularize complex components by breaking them into smaller pieces
Rationale:
Example:
// ā BAD: Creating simplified version // CodexEditor.tsx (existing complex component) // CodexEditorSimple.tsx (new simplified version) ā AVOID THIS // ā GOOD: Modularizing complex component // CodexEditor.tsx (main orchestrator) // āāā CodexEditorHeader.tsx (extracted module) // āāā CodexEditorFields.tsx (extracted module) // āāā CodexEditorToolbar.tsx (extracted module) // āāā hooks/ // āāā useCodexState.ts (extracted logic) // āāā useCodexValidation.ts (extracted logic)
See ADR-012: Codices as File Containers for architectural context.
Templates are the core of the system and must be carefully constructed:
Template composition is essential for task automation - see ADR-013: Template Composition.
Virtualization from the Start:
See ADR-014: Content Chunking for size limit strategies.
When implementing save/sync features, consider the Bindery CRDT infrastructure:
# Monorepo-wide operations pnpm install # Install all dependencies pnpm build # Build all packages pnpm test # Run all tests pnpm lint # Lint all packages # Package-specific operations 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 # Git operations git add packages/ # Stage package changes git commit -m "feat(scriptorium): description"
# Core tests cd packages/vespera-scriptorium pytest # Run all tests with pytest python3 run_mcp_tests.py # Run MCP-specific tests # Specific test suites pytest test_bindery_tools_mock.py # Test Bindery integration pytest test_mcp_server_complete.py # Test MCP server completeness pytest test_integrated_backend.py # Test backend integration # MCP tool testing python3 mcp_server.py # Start server # Use MCP tools via Claude Code to test functionality
packages/vespera-scriptorium/CLAUDE.mdPRPs/CLAUDE.mdPRPs/vespera-scriptorium-transition/README.mddocs/architecture/core/PROJECT_CENTRIC_ARCHITECTURE.mddocs/architecture/core/HIERARCHICAL_TEMPLATE_SYSTEM.mddocs/architecture/core/CODEX_NESTING.mddocs/README.mdClone and Setup:
cd /home/aya/dev/monorepo/vespera-atelier pnpm install
Install Vespera Scriptorium:
cd packages/vespera-scriptorium pip install -r requirements.txt
Test System:
# Run tests pytest python3 run_mcp_tests.py
Configure MCP Server (user scope):
# Add to user config (one-time setup) claude mcp add -s user vespera-scriptorium python3 /path/to/vespera-atelier/packages/vespera-scriptorium/mcp_server.py # Test server directly python3 mcp_server.py
Use MCP Tools:
# Available via Claude Code MCP integration: # - Task management: create_task, get_task, update_task, delete_task, list_tasks # - Task execution: complete_task, execute_task, assign_role_to_task # - Project management: create_project # - Search & indexing: search_entities, index_document # - Monitoring: get_dashboard_stats, health_check, list_roles
The Vespera Atelier is an ecosystem of intelligent tools for creative professionals, researchers, and knowledge workers. The revolutionary Dynamic Automation and Tag-Driven Systems transform static content into reactive, intelligent ecosystems.
#peaceful#tenseš Comprehensive Documentation: See
/docs/Phase 15 Foundation Documents (ā Start Here):
Core System Architecture:
Planned Features (š® Not Yet Implemented):
Examples and Guides:
When working on specific components, ALWAYS reference the relevant architectural documents:
Required Reading:
Key Implementation Notes:
Required Reading:
Key Implementation Notes:
Required Reading:
Key Implementation Notes:
Required Reading:
Key Implementation Notes:
Required Reading:
Current Architecture:
archive/legacy/This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). All packages in this monorepo share this license to ensure open-source collaboration.
Remember: This is a monorepo. Think in terms of packages, workspaces, and coordinated development.