| 1 |
# Sprint plan: Spectra 0.1, Talk |
| 2 |
|
| 3 |
Each loop iteration: pick the first unchecked item, implement it with tests, run the gated checks, commit with `oxy`, tick the box here with a one-line note, and commit again. Update `docs/spec.md` (and its changelog) whenever behaviour the spec describes changes. If an item cannot be finished in two iterations, note why under it and move on. The issues are on https://oxygenhub.io/projects/andymccall/7. Sprint 1 built 0.1 on one machine; Sprint 2 makes it client and server (spec §8.6), since Andy runs the daemon on Earth and everything else on his workstation. |
| 4 |
|
| 5 |
## Rules |
| 6 |
|
| 7 |
- Never run `git init` in this directory or push this project anywhere but its `oxygenhub` remote. Commit with `OXY_HOME=~/.oxy-agents/claude oxy commit -m "..." PATHS..`, never with Andy's own key. |
| 8 |
- Tests are hermetic: a temporary data directory, a temporary socket, port 0; never `~/.local/share/spectra`, `~/.config` or the network. |
| 9 |
- Gate every commit on `make check` (changelog, fmt, clippy with warnings as errors, tests), chained so a failing gate stops the commit: `make check && oxy commit …`. |
| 10 |
- Every code change adds a CHANGELOG.md line under `## Unreleased`, or sets `NO_CHANGELOG=1`. |
| 11 |
- Never weaken a security goal of spec §5 to make a test pass. |
| 12 |
- Never commit or push anything under `docs/prompts/` (Andy's prompts; ignored in `.oxyignore`). Name the paths in every commit. |
| 13 |
- Never act as Andy: owner-only steps (delegating to an agent key, the acceptance run) wait for him. |
| 14 |
|
| 15 |
## Sprint 1 (done) |
| 16 |
|
| 17 |
- [x] #1 Project skeleton in Oxygen's shape — done 2026-11-02: workspace, deps/oxygen pinned, make check, deps-check (212 crates, all vendored). |
| 18 |
- [x] #2 CI on OxygenFlow — done 2026-11-02: run #1 passed fmt, clippy, test, build with no image rebuild. |
| 19 |
- [x] #3 The ledger — done 2026-11-02: chain, frozen envelope, HLC, signed checkpoints every 256 events, verify/check/rebuild; append 0.15 ms (release), 10,000 random events with rebuild and verify 1.3 s. |
| 20 |
- [x] #4 Identities instead of tokens — done 2026-11-02: init, agent add (waits for the delegation), list, disable, identity show/refresh; Principals replay in verify; Authenticator (window, nonce, uid); write lock. Checked against the real `oxy identity delegate add`. The socket and its SO_PEERCRED arrive with #7, which uses the Authenticator. |
| 21 |
- [x] #5 Projects, presence and sessions — done 2026-11-02: project add/list with relations from .oxymodules (checked on oxygen, oxygenflow, oxygenhub, spectra), presence and session trackers with events and projections; the daemon feeds them from #7. |
| 22 |
- [x] #6 Channels, threads, messages, inbox and search — done 2026-11-02: spectra-core::conversation (post, read, inbox, ack, redact, search, direct channels), shared by tools, API and CLI. |
| 23 |
- [x] #7 Tuner: MCP over Streamable HTTP — done 2026-11-02: spectra serve, socket + loopback, signed requests, both revisions, refusals, owner events through the daemon; end-to-end tests drive the real binary. |
| 24 |
- [x] #8 The 0.1 tools — done 2026-11-02: eleven tools through one invoke wrapper (record, rules line); wait with the idle guard; end-to-end tests with two agents. Found while testing: serve could hang on shutdown with a stream open (now five seconds at most). |
| 25 |
- [x] #9 The stdio shim — done 2026-11-02: spectra mcp --agent NAME, driven over pipes in tests/cli_mcp.rs. Real Claude Code, Antigravity and Kimi connections are checked in #13 with Andy, since they need his MCP configuration. |
| 26 |
- [x] #10 Radar — done 2026-11-02: Live, Channels, channel/thread with compose, Log with Verify now; spectra open; checked by hand in Chrome on a demo Spectra. That demo found the ledger cancellation bug (fixed, regression test fails on the old code) and a referrer policy that blanked the Origin of form posts. |
| 27 |
- [x] #11 JSON API and spectra-api types — done 2026-11-02: every 0.1 endpoint, problems, paging, ETags, the live log; types and ts/index.d.ts. How spectra-vscode will sign is spec open question 11. |
| 28 |
- [x] #12 Human CLI — done 2026-11-02: say, inbox --follow, search, api (the signing proxy for spectra-vscode); tests/cli_json.rs parses every --json output with and without the daemon. |
| 29 |
- #13 Acceptance moved to Sprint 2, to run across two machines. |
| 30 |
|
| 31 |
## Sprint 2: client and server |
| 32 |
|
| 33 |
- [x] #20 Server over TLS — done 2026-11-03: own certificate in keys/tls.*, vouched for by a signed instance.tls event; GET /api/v1/instance; pinned client transport; a uid-bound agent refused over TCP; tests/tls.rs. |
| 34 |
- [ ] #22 Remote setup: spectra init --owner KEYID and the owner's claim from the client. |
| 35 |
- [ ] #21 spectra connect and the TLS client: trust through the owner's delegation, pinned certificate, shims over the network. |
| 36 |
- [ ] #23 The CLI without a ledger file: every command through the JSON API. |
| 37 |
- [ ] #24 Radar from a workstation: spectra open's loopback proxy to the pinned server. |
| 38 |
- [ ] #25 Run the daemon on Earth: install over SSH, a unit that waits for a Spectra, README. |
| 39 |
- [ ] #13 Acceptance (with Andy), across two machines. Ready when the rest is done: |
| 40 |
1. On Earth (the claude account, no key of Andy's): `spectra init --owner KEYID`; the service starts. |
| 41 |
2. On the workstation: `spectra connect https://earth.andymccall.xyz:7350`; run the printed `oxy identity delegate add … --scope changes`; `spectra connect` again, which claims Earth as Andy's. |
| 42 |
3. `spectra project add ~/development/oxygen` and `~/development/oxygenhub`. |
| 43 |
4. `spectra agent add claude-oxygen --kind claude-code --project oxygen --home ~/.oxy-agents/claude-oxygen`, then the printed delegation; the same for `antigravity-oxygenhub`. |
| 44 |
5. Claude Code in oxygen: `claude mcp add spectra -- spectra mcp --agent claude-oxygen`; Antigravity in oxygenhub: the README's `mcp_config.json` line. |
| 45 |
6. Both call `brief`, post in #general, and see each other's messages; watch with `spectra open`. |
| 46 |
7. `spectra admin verify`; on a copy of Earth's database, edit a row and see verify catch it. |
| 47 |
8. Cut 0.1.0 in CHANGELOG.md and tag it. |
| 48 |
|
| 49 |
## Log |
| 50 |
|
| 51 |
- 2026-11-02 plan created; sprint adjusted to spec Draft 0.3 (identities and the ledger). |
| 52 |
- 2026-11-02 #1 and #2 done (CI green on run #1); #3 done. Root disk was full: build trees go to /mnt/development/spectra-target (CARGO_TARGET_DIR). |
| 53 |
- 2026-11-02 #4 done. Found and fixed while testing: a signed event's actor was not checked against its signer. |
| 54 |
- 2026-11-02 Andy asked for an oxy-style CLI: every command now reports through oxy's ui module. #5 done. |
| 55 |
- 2026-11-02 #11 and #12 done. Measured in release with 1,000 messages, round trip over the socket including signing (tests/bench.rs): brief 2.7 ms (target 5), say 3.1 ms (target 10), wait wakes 4.2 ms after a mention (target 100). A single ledger append 0.15 ms. 58 tests. #13 is ready for Andy. |
| 56 |
- 2026-11-03 Sprint 2 set up: Andy wants the daemon on Earth and the rest on his workstation. Spec Draft 0.4 adds client and server (§8.6); #20–#25 opened, #13 moved and rewritten for two machines. The binary and an enabled, waiting user unit are already on Earth (claude account, lingering on). |