Add CLAUDE.md, README, and development tooling docs

- CLAUDE.md: project context for Claude Code sessions - README.md: human-facing project intro, structure, getting started - docs/tooling.md: cmux, Claude Code, Crit, and OpenSpec workflow Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-22 12:06:51 +01:00 · 2026-03-22 12:06:51 +01:00 · 48547fdc82
commit 48547fdc82
parent 4214564fd8
3 changed files with 293 additions and 0 deletions
--- a/docs/tooling.md
+++ b/docs/tooling.md
@ -0,0 +1,109 @@
+# Development Tooling
+
+This project is built using AI-assisted, spec-driven development. Here are the
+main tools used in the development workflow.
+
+## cmux
+
+**Native macOS terminal for AI coding agents**
+
+- Website: https://cmux.dev
+- GitHub: https://github.com/manaflow-ai/cmux
+
+cmux is a native macOS terminal app purpose-built for running AI coding agents
+like Claude Code. It provides vertical tabs, split panes, and smart
+notifications that show which panes need attention — ideal for running multiple
+Claude Code sessions in parallel across different parts of the monorepo.
+
+Key features we use:
+- Split panes for Planner and Journal development side by side
+- Notification badges when a Claude Code session needs input
+- Native performance (Swift/AppKit, not Electron)
+
+## Claude Code
+
+**AI coding assistant (CLI)**
+
+- Website: https://claude.ai/claude-code
+- Docs: https://docs.anthropic.com/en/docs/claude-code
+
+Claude Code is the primary development tool for this project. It reads the
+codebase, understands the architecture (via `CLAUDE.md`), and implements
+features from OpenSpec tasks.
+
+Key integrations:
+- `CLAUDE.md` at repo root provides project context
+- OpenSpec slash commands (`/opsx:propose`, `/opsx:apply`, etc.)
+- Crit integration for code review
+
+## Crit
+
+**Inline code review tool**
+
+- GitHub: https://github.com/tomasz-tomczyk/crit
+
+Crit provides browser-based inline review for files and diffs. It's used in
+the development workflow for reviewing architecture plans, specs, and code
+changes before committing.
+
+How we use it:
+- Review architecture and design documents with inline comments
+- Claude Code addresses review comments and re-opens for another round
+- Iterate until the reviewer clicks "Finish Review" with no comments (approved)
+
+Usage:
+```bash
+crit <file>              # Review a specific file
+crit                     # Review git diff (uncommitted or branch changes)
+crit share <file>        # Share a review via URL
+```
+
+## OpenSpec
+
+**AI-native spec-driven development**
+
+- Website: https://openspec.dev
+- GitHub: https://github.com/Fission-AI/OpenSpec
+
+OpenSpec structures the development workflow around specifications. Each feature
+starts as a "change" with four artifacts:
+
+1. **proposal.md** — Why this change is needed and what capabilities it adds
+2. **design.md** — Technical decisions and architecture
+3. **specs/** — Testable requirements with WHEN/THEN scenarios
+4. **tasks.md** — Implementation checklist
+
+Workflow:
+```bash
+# Propose a new feature (generates all artifacts)
+/opsx:propose "add route sharing"
+
+# Implement tasks from a change
+/opsx:apply
+
+# Archive when done
+/opsx:archive
+```
+
+OpenSpec files live in `openspec/` at the repo root. The current active change
+is `openspec/changes/phase-1-mvp/`.
+
+## How They Work Together
+
+```
+1. Plan          cmux + Claude Code + Crit
+                 Draft architecture → review with Crit → iterate
+
+2. Specify       Claude Code + OpenSpec
+                 /opsx:propose → generates proposal, design, specs, tasks
+
+3. Implement     cmux + Claude Code + OpenSpec
+                 /opsx:apply → Claude Code works through tasks
+                 Run multiple sessions in cmux split panes
+
+4. Review        Crit
+                 Review changes in browser → address comments → approve
+
+5. Ship          Claude Code
+                 Commit, push, deploy
+```