trails/docs/tooling.md

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:

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:

# 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