Development guidance for Vespera Atelier monorepo - an intelligent platform for document-centric orchestration, task management, and creative workflows with MCP integration
Development guidance for working in the Vespera Atelier monorepo - an intelligent platform for document-centric orchestration, task management, and creative workflows.
```
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
```
**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
**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
**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
**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
**Claude Code automatically switches to `packages/vespera-scriptorium`** as working directory due to workspace configuration.
```bash
cd /home/aya/dev/monorepo/vespera-atelier && [command]
ls /home/aya/dev/monorepo/vespera-atelier/PRPs/
pwd
```
```bash
cd packages/vespera-scriptorium
pip install -e .
pytest tests/
```
```bash
pnpm build # Build all packages
pnpm test # Test all packages
pnpm scriptorium:dev # Run specific package
```
The MCP server in `packages/vespera-scriptorium/` uses FastMCP as a translation layer to the Rust Bindery backend.
```bash
cd packages/vespera-scriptorium
pip install -r requirements.txt
python3 mcp_server.py
claude mcp add -s user vespera-scriptorium python3 /path/to/vespera-atelier/packages/vespera-scriptorium/mcp_server.py
/mcp reconnect vespera-scriptorium
```
**14 MCP Tools Available:**
**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)
```
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
Consider Bindery CRDT infrastructure:
```bash
pnpm install # Install all dependencies
pnpm build # Build all packages
pnpm test # Run all tests
pnpm lint # Lint all packages
```
```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
```
```bash
cd packages/vespera-scriptorium
pytest
python3 run_mcp_tests.py
pytest test_bindery_tools_mock.py # Bindery integration
pytest test_mcp_server_complete.py # MCP server completeness
pytest test_integrated_backend.py # Backend integration
```
```bash
git add packages/
git commit -m "feat(scriptorium): description"
```
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
**MCP Server:**
**Testing:**
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
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/vespera-atelier-monorepo-development/raw