# 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.
