# Contributing to Spool
Thanks for your interest in contributing to Spool! This document covers the development setup, conventions, and process.
## Development Environment
### Prerequisites
- Rust stable toolchain (edition 2024)
- Cargo (comes with Rust)
- An Obsidian vault (for integration testing, optional)
### Setup
```bash
git clone https://github.com/lukylong/Spool.git
cd spool
cargo build
cargo test
```
### Build Targets
```bash
# Default build (CLI + MCP + daemon)
cargo build
# With GUI workbench (requires egui dependencies)
cargo build --features gui
# Release build
cargo build --release
```
## Code Style
### Formatting
- Use `cargo fmt` before committing
- Use `cargo clippy` to catch common issues
### Conventions
- Immutable data by default — create new objects rather than mutating
- Small files (200-400 lines typical, 800 max)
- Small functions (under 50 lines)
- Explicit error handling at every level (no silent swallowing)
- Validate inputs at system boundaries
### Architecture Principles
- Shared Rust core serves all surfaces (CLI, MCP, daemon, desktop)
- Append-only ledger is the source of truth for lifecycle data
- Obsidian vault is the source of truth for curated knowledge
- Daemon is optional and read-only
- Prefer extending shared layers over adding surface-specific logic
## Testing
### Running Tests
```bash
# Full suite
cargo test
# Quick check
cargo test -q
# Specific areas
cargo test -q cli_smoke
cargo test -q mcp_smoke
cargo test -q daemon_smoke
cargo test -q lifecycle_store --lib
cargo test -q lifecycle_service --lib
```
### Test Requirements
- All PRs must pass `cargo test`
- New features should include tests
- Bug fixes should include a regression test
- Integration tests live in `tests/`
- Unit tests live alongside the code they test
### Benchmarks
```bash
cargo bench --bench retrieval
```
## Pull Request Process
1. Fork the repository
2. Create a feature branch from `main`
3. Make your changes
4. Run the full test suite: `cargo test`
5. Run lints: `cargo clippy -- -D warnings`
6. Run format check: `cargo fmt --check`
7. Submit a PR with a clear description
### Commit Messages
Use conventional commits:
```
<type>: <description>
<optional body>
```
Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`
### PR Description
- Summarize what changed and why
- Note any breaking changes
- Include test plan or verification steps
## Project Structure
```
src/
├── cli/ — CLI argument parsing and command handlers
├── config/ — Configuration loading and validation
├── domain/ — Core types (memory types, scopes, lifecycle states)
├── engine/ — Project matching, scoring, candidate selection
├── vault/ — Markdown scanning, frontmatter, wikilinks
├── output/ — Prompt/markdown/JSON renderers
├── bin/ — Binary entrypoints (MCP, daemon, GUI)
├── mcp.rs — MCP server implementation
├── daemon.rs — Daemon read boundary
├── desktop.rs — Desktop facade layer
├── lifecycle_store.rs — Append-only ledger storage
├── lifecycle_service.rs — Service layer for lifecycle operations
└── vault_writer.rs — Vault writeback from lifecycle records
tests/
├── cli_smoke.rs — CLI integration tests
├── mcp_smoke.rs — MCP integration tests
└── daemon_smoke.rs — Daemon integration tests
```
## Questions?
Open an issue for questions about the codebase or contribution process.