samiandClaude Opus 5
8bb683b09d
Lays out Velox Download Manager (IDM-class download manager for Ubuntu 26.04) as a monorepo ready for parallel lane development. No implementation code by design. - docs/: architecture, roadmap M0-M7, IDM-parity GUI spec, engine design, Firefox extension spec, risks/spikes, packaging - contracts/: wire-contract skeleton (JSON Schema + fixture templates) — the single synchronization point between lanes - docs/agents/: one brief per lane (PROTO, CORE, DAEMON, GUI, EXT, PKG/QA) with owned directories, build order and definition of done - CLAUDE.md: rules of engagement — lane ownership, layering, non-negotiables - CMake scaffolding with dev/tsan/release/ci presets Two environment findings shape the design: Firefox here is the Mozilla snap (native-messaging risk, so the extension carries a loopback-WebSocket fallback), and Wayland forbids passive clipboard monitoring (so clipboard capture is explicit-action-first). Co-Authored-By: Claude Opus 5 <[email protected]>
71 lines
3.2 KiB
Markdown
71 lines
3.2 KiB
Markdown
# Rules of engagement — agents working in this repo
|
|
|
|
Read this before touching anything. Then read your lane brief in [docs/agents/](docs/agents/).
|
|
|
|
## 1. Stay in your lane
|
|
|
|
| Lane | Owns | Never writes |
|
|
|---|---|---|
|
|
| PROTO | `contracts/`, `tools/mockd/`, `tests/conformance/` | everything else |
|
|
| CORE | `core/`, `tools/bench/`, `tools/fuzz/` | `daemon/`, `gui/`, `extension/`, `contracts/` |
|
|
| DAEMON | `daemon/`, `cli/`, `nmhost/`, `packaging/nativehost/` | `core/`, `gui/`, `extension/`, `contracts/` |
|
|
| GUI | `gui/` | everything else |
|
|
| EXT | `extension/` | everything else |
|
|
| PKG/QA | `packaging/`, `.github/`, `tools/testserver/`, `tests/integration/`, `tests/e2e/`, root build files | any lane's feature code |
|
|
|
|
If your task seems to require editing another lane's files, that is a signal the interface
|
|
is wrong. **File the request; don't reach across.**
|
|
|
|
## 2. `contracts/` is sacred
|
|
|
|
- Only PROTO commits there.
|
|
- Generated code (`core/generated/`, `extension/src/shared/protocol/`) is committed and
|
|
**must never be hand-edited**. Fix the schema, regenerate.
|
|
- Need a new field? Open a `contracts/`-only PR: schema + fixtures + regenerated code +
|
|
`VERSION` bump. Optional field or new method = minor; rename/remove/retype = major + ADR.
|
|
- Working around a wrong contract locally is the single failure mode most likely to sink
|
|
this project. Don't.
|
|
|
|
## 3. Layering
|
|
|
|
```
|
|
core → no JSON, no SQL, no Qt, no RPC. Ever.
|
|
daemon → depends on core. No Qt.
|
|
gui / ext → zero download logic. They render state and forward user intent.
|
|
nmhost → a dumb pipe. Under 300 lines. No logic.
|
|
```
|
|
|
|
A grep for `curl|pwrite|sqlite` in `gui/` must come back empty. Same for download logic in
|
|
`extension/`.
|
|
|
|
## 4. Non-negotiable behaviours
|
|
|
|
- **Capture fails open.** Daemon down, slow, or erroring → Firefox downloads normally.
|
|
Never swallow a user's download. `capture.offer` answers within 750 ms or the extension
|
|
gives up.
|
|
- **Resume is validated.** `If-Range` with ETag/Last-Modified; a `200` where `206` was
|
|
expected means the file changed — ask the user, never silently corrupt.
|
|
- **Never bind beyond `127.0.0.1`.** The WS transport is token-authenticated, origin-checked,
|
|
and rate-limited.
|
|
- **Secrets go to the Secret Service**, never SQLite, never logs.
|
|
- **Paths are canonicalized** and checked against allowed roots before any write.
|
|
- **No allocation in the transfer hot path.**
|
|
|
|
## 5. Definition of done, everywhere
|
|
|
|
Code + tests + docs updated in the same change. A feature with no test does not exist. If
|
|
you change observable behaviour, update the doc in `docs/` that describes it in the same PR.
|
|
|
|
## 6. Style
|
|
|
|
- C++23, `-Wall -Wextra -Werror`, clang-format (config at root), clang-tidy clean.
|
|
- TypeScript strict mode, ESLint, no `any` on protocol boundaries.
|
|
- Commit messages: `lane: imperative summary` (e.g. `core: add dynamic segment stealing`).
|
|
- One logical change per commit. Rebase onto `main`; no merge commits.
|
|
|
|
## 7. When you're unsure
|
|
|
|
Ask in the PR rather than guessing at the interface. A day of clarification is cheaper than
|
|
an M2 integration rewrite. And record real decisions as an ADR in `docs/adr/` — the next
|
|
agent to touch this will have none of your context.
|