From dc963a27f72a6a54e68af7c6f53aaf1537c8a426 Mon Sep 17 00:00:00 2001 From: naps62-yolo Date: Sun, 24 May 2026 12:05:27 +0000 Subject: [PATCH] docs(maestro): add repo-level CLAUDE.md Orients future sessions and Linear-driven skills: points at the spec, the Linear project, the dependency chain (NAP-211 is the starting point), the target workspace layout, and conventions (TDD, conventional commits with maestro scope, real tmux+git in integration tests, no mocking). Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ba48727 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# Maestro + +A unified terminal-session orchestrator. One place — laptop, desktop, or phone — to see and attach to every interactive shell or agent (Claude Code, opencode, plain bash) running across every machine you care about. tmux for persistence, WebSocket for transport, daemon-per-host federated by a small always-on registry. + +## Where the spec lives + +`docs/superpowers/specs/2026-05-24-maestro-design.md` is the source of truth for architecture, wire protocol, session model, auth, repo layout, and scope boundary. **Read it before writing any code in this repo.** + +## Where the work is + +Linear project **Maestro** under team **Naps62**. Issues `NAP-211..218` cover the prototype; each has `blockedBy` set so the dependency chain is explicit. **`NAP-211` is the only unblocked starting point.** + +`.claude/linear.json` wires `/yolo` and `/work` to this project — they pick from "available now" (status backlog/pending, not blocked). + +## Repo layout (target) + +Cargo workspace, populated incrementally starting with NAP-211: + +``` +crates/ +├── maestro-protocol/ # shared wire types (NAP-211) +├── maestro-daemon/ # per-host tmux wrapper + WS endpoints (NAP-212, NAP-214) +├── maestro-registry/ # always-on phone book + HTTP API (NAP-213, NAP-215) +├── maestro-cli/ # `maestro list/spawn/attach/kill` (NAP-216) +└── maestro-e2e/ # cross-process integration tests (NAP-217) +web/ # browser client (NAP-218, plan 2) +``` + +## Conventions + +- **TDD by default.** Failing test first, then minimal impl. Commit test + impl together. +- **Frequent commits.** One logical unit per commit; don't pile work up. +- **Conventional commits with `maestro` scope.** Example: `feat(maestro): add Hello message round-trip test`. +- **`cargo fmt` + `cargo clippy --all-targets -- -D warnings`** before every commit. (Add to CI as part of NAP-211.) +- **Integration tests use real `tmux` and `git`.** Don't mock them. Isolate via temp `$HOME` and `TMUX_TMPDIR`. + +## Network assumption + +Maestro is network-agnostic. The operator chooses bind addresses; the perimeter is whatever VPN (Wireguard, etc.) or private LAN they've set up. Maestro does not terminate TLS itself or police the network. See spec §Auth. + +## Status + +Empty repo. Spec approved and committed. **NAP-211 is the natural start.**