markplane

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Markplane is an AI-native, markdown-first project management system. "Mark" (markdown) + "plane" (control plane). The repo itself is the project manager — no database, no SaaS. Files are the source of truth, git is the changelog.

**Tech stack**: Rust CLI binary with integrated MCP server (`markplane mcp` subcommand) wrapping a shared core library. React + Tailwind web UI via `markplane serve`.

## Build & Test

Requires Rust 1.93.0+ (edition 2024). Web UI also requires Node.js 18+.

```bash
cargo build --workspace              # Build all crates
cargo test --workspace               # Run all tests
cargo clippy --workspace             # Lint (must be warning-free)
```

Web UI (optional):
```bash
cd crates/markplane-web/ui && npm install && npm run build   # Build frontend
cargo install --path crates/markplane-cli --features embed-ui # Single binary with embedded UI
```

After code changes, `cargo install --path crates/markplane-cli` to update the local `markplane` binary.

## Workspace Structure

| Crate | Type | Role |
|-------|------|------|
| `markplane-core` | Library | Data models, CRUD, sync, references, context generation |
| `markplane-cli` | Binary (`markplane`) | CLI commands, MCP server (`markplane mcp`), web server (`markplane serve`) |
| `markplane-web/ui` | Next.js app | React + Tailwind frontend (static export, optionally embedded via `rust-embed`) |

## Key Conventions

- **Error handling**: `thiserror`/`MarkplaneError` in core, `anyhow` in CLI, `Result<String, String>` in MCP tool handlers
- **No regex**: Reference extraction (`[[ID]]`) uses manual byte scanning
- **`serde_yaml 0.9`**: Deprecated but kept — `serde_yml` is too immature
- **Integration tests**: Use `cargo_bin_cmd!()` macro (not deprecated `Command::cargo_bin()`)
- **Derived files**: INDEX.md and `.context/` are gitignored within `.markplane/` — fully regenerated by `markplane sync`
- **Auto-sync**: Runs on `markplane init`, `markplane mcp` startup, and `markplane serve` startup
- **ID system**: `{PREFIX}-{RANDOM}` with 5-char alphanumeric suffix (no sequential counters)

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed patterns, error handling, code style, and how to add new commands/tools.

## Documentation

- [Architecture](docs/architecture.md) — System design, data model, crate responsibilities
- [File Format](docs/file-format.md) — Directory structure, YAML schema, ID system, cross-references
- [CLI Reference](docs/cli-reference.md) — All commands with examples
- [MCP Setup](docs/mcp-setup.md) — AI tool integration, tool/resource catalog
- [Web UI Guide](docs/web-ui-guide.md) — Dashboard usage and development workflow
- [Getting Started](docs/getting-started.md) — Step-by-step tutorial
- [Releasing](docs/releasing.md) — Release process and versioning

## Project Management

This project uses Markplane for project management. Key files:
- `.markplane/INDEX.md` - Navigation entry point
- `.markplane/.context/summary.md` - Current project state
- `.markplane/backlog/INDEX.md` - All work items
- `.markplane/plans/INDEX.md` - Implementation plans
When working on a task, read the relevant task item and its linked plan first.