48547fdc82
- 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>
109 lines
3.3 KiB
Markdown
109 lines
3.3 KiB
Markdown
# 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
|
|
```
|